NewsAgent Version 1.0 Copyright © Rob Young 1997.
Permission to use, copy, and distribute this software and its documentation without fee for NON-COMMERCIAL purposes is hereby granted, according to the details contained in the enclosed license.htm. Please read that document before continuing. COMMERCIAL USERS ARE REQUIRED TO REGISTER this software before using it in connection with any commercial enterprise, including its publication on any World Wide Web site intended to publicize, form a part of, or otherwise assist a commercial venture. Non-commercial users are (of course!) encouraged to register, but are under no obligation to do so. All registered users will be entitled to 6 month's free email support, free updates of the registered title if and when available, and notification of new titles. For details of pricing and registration, read the accompanying document register.htm. USE OF THIS SOFTWARE IS TAKEN TO INDICATE ACCEPTANCE OF THE ABOVE TERMS, AND THOSE LAID OUT IN THE ACCOMPANYING LICENSE DOCUMENT. NewsAgent is a news-ticker applet that displays text included within an HTML parameter or retrieved from a remote text file.When used in "remote" mode, NewsAgent will regularly check for updates to the text file at specified intervals. The display font and all colors are editable, and there are various background options including the placement of a background image. The chosen text can be set to loop a specified number of times, or indefinitely, and animation delays are editable. A mouse click within the applet area can toggle the animation between pause/resume, or open a URL, according to chosen mode. Tooltip messages can optionally be displayed within the applet area when the mouse enters. NewsAgent also (optionally) supports sounds, although I'd be the first to admit that these can get irritating <g>.
Place the file ryNewsAgent.class in the same folder as the the HTML document in which you want to use the applet. If you want to use sounds, place the sound files into that folder too. Add the following code to your HTML page. (This is a working example, which you might like to use as a basis for working while you read the rest of this documentation. The "params.txt" file is included in the zip archive.) <applet code=ryNewsAgent.class width=350 height=227> <param name=ScriptFile value="params.txt"> <param name=DefaultText value="What's happening at CodeBase?|A new applet called NewsAgent, that's what!"> <param name=Font value="Dialog,plain,14"> <param name=TextColor value="F0F0FF"> <param name=BgColor value="8080FF"> <param name=BgImage value="bluepaper.JPG"> <param name=3DBorder value="raised"> <param name=MarginWidth value="40"> <param name=CharacterDelay value="20"> <param name=ParagraphDelay value="500"> <param name=RepeatDelay value="500"> <param name=Loop value="infinite"> <param name=Update value="10"> <param name=Sound value="no"> <param name=OnClick value="hold"> <param name=URL value="http://www.btinternet.com/~ry/CodeBase"> <param name=Target value="_top"> <param name=UseTooltips value="yes"> <param name=TooltipColor value="F0F0FF"> <param name=TooltipBgColor value="000080"> <param name=LinkMessage value="Find out what's making news at CodeBase!"> </applet> If you're experienced in HTML and you've used Java™ applets and the <APPLET> tag, all this should be painfully obvious - you might prefer to skip to the next section. If you're not used to applets, PLEASE read this, especially the bit about the CODEBASE attribute. I get so many emails about this it's ridiculous, and spend a lot of time just repeating the next paragraph in replies. It isn't that I'm not willing to help, but this is me helping... codebase The location in which the class file (ryNewsAgent.class) can be found, relative to the directory containing the HTML document in which you've used the applet. By default, a browser will search for an applet's class file in the folder containing the currently open web page. If that's where you've put the class file, leave out the codebase attribute. If you've put the class file in a subfolder of the current folder called, for example, 'classes', put in that attribute so that it reads: CODEBASE="classes". If this seems confusing, look at it this way: when you use an image on a web page, you have to enter the relative path to the image using the <IMG SRC=> attribute. In the case of images, the SRC= attribute includes both the path to the file and the name of the file. In the APPLET tag, these details are split between two separate attributes: CODEBASE= specifies the path to the class file, and CODE= specifies its name. Therefore, just as with images, if there's no path that the browser needs to follow to find the file, all you need to enter is the filename. Alternatively, if you get into a pickle with this, you could put in the absolute URL to the class file instead, such as CODEBASE="http://www.my_isp/~me/myfolder/mysubfolder". code This should always read "ryNewsAgent.class", and case is vital. width The width of the applet. NewsAgent automatically wraps text according to applet width (and your MarginWidth setting, below) so you can set this to be as narrow or wide as you wish. height The height of the applet. Again, any height you choose is fine, but bear in mind that a larger height gives visitors to your page more chance to read the text before it vanishes 'off the top'! Quick Tip: When setting up the applet dimensions, it's far easier if you use the BgColor parameter (below) to temporarily set the applet background to a color that stands out from your page background. When you've set the dimensions to your liking, return the BgColor setting to the color you wanted. vspace Creates space above and below the applet. The default is 0, but you might want to use this to put some fresh air between the applet and any text or images that appear around it on the page. Note that different browsers apply their HSPACE and VSPACE in different ways: Internet Explorer divides the amount evenly left and right (or above and below), while Netscape sticks the whole lot below (or to the right). There are far more reliable ways to create space around web page elements that HSPACE and VSPACE, and I strongly suggest you use one of those instead until everyone gets their act together. hspace Creates horizontal space around the applet. See vspace, above. align=top Align settings for the <APPLET> tag work like those for <IMG>. Using top will ensure that your applets will be placed side by side if you're using a row of NewsAgents, regardless of the applets' height-settings. Use left or right if you want to place a paragraph of text to one side of the applet. With just about everything being customizable, NewsAgent can obviously take a fair bundle of parameters. The good news is that the applet will run quite happily (although not wholly usefully) with no parameters at all. In other words, everything has a default setting - if you're satisfied with some of the defaults, you can leave those parameters out of your HTML <APPLET> code. ScriptFile The path to, and name of, a text file whose contents should be displayed by the applet. This is in the form of a URL, and may be relative (such as "textfile.txt" or "../files/textfile.txt") or absolute (such as "http://www.protestors.com/plain.txt"). The relative URLs are specified in relation to the location of the HTML document containing the applet, as you'd expect. If no ScriptFile parameter is included, the text given in the DefaultText parameter will be used instead. Bear in mind that NewsAgent reads only plain text. The filename you specify can have any extension you like, but don't expect it to read a Microsoft Word document with full formatting. DefaultText If you prefer not to use the ScriptFile parameter to enter your text, you're probably crazier than I am. However, you can enter as much text as you like in the DefaultText parameter instead. To create paragraph breaks, enter the pipe symbol ( | ) in the appropriate places, as in the example code above. If you've chosen not to use the ScriptFile parameter, and you've somehow forgotten to include the DefaultText parameter, the following text will be shown instead: ****Please enter the path to a text file in the ScriptFile parameter, and/or a valid string in the DefaultText parameter**** Font A comma-delimited value for the font to be used for the text display. The default settings are Dialog, style plain, at size 14, which would be written as Dialog,plain,14. Two important things to note: first, there must be no spaces in this entry; second, the three items must appear in the order name,style,size. Note that the style part of this setting can be plain, bold, italic or bolditalic, and these are not case-sensitive. By the way, I get a lot of email asking why Futura Book or BrushScript won't work. Java has its own tiny collection of fonts available and has no support for TrueType fonts. Your possible choices are Dialog, TimesRoman, Helvetica or Courier. It's sad, but it's true. TextColor The color of the font to be used for the text display, as a hex triplet. The default is a sober 000000 (black). BgColor The applet's background color as a hex triplet, the default being FFFFFF (white). You might wish to set this to match your page's <BODY> background color, or to something different to make the applet stand out. Your choice of color here should be made in conjunction with your setting for 3DBorder, below. BgImage Allows you to specify an image to use as the applet background. If you include this parameter, it overrides your settings for BgColor and 3DBorder. Just as with the ScriptFile parameter mentioned above, the location of the BgImage can be given as a relative or an absolute URL. The image you select will be automatically resized to fit your applet dimensions. It will not be tiled, but you'll never have to worry about it not being big enough to fill the entire applet area. Bear in mind, though, that this may create some distortion of the image - you may prefer to create an image that matches your applet dimensions, or (in reverse) to match your applet dimensions to those of your image, to ensure that the image is crystal clear. 3DBorder This parameter has an effect only when the BgImage parameter is excluded. Your three possible options here are raised (which creates a raised 3D border using the BgColor), lowered (creating a depressed 3D border using the BgColor), or off, which gives no 3D effect. None of these values is case-sensitive. Note that if you choose lowered, the BgColor you chose will be darkened considerably. The default setting is off. MarginWidth Sets the width of the left and right margins, in pixels. The default is 10. CharacterDelay You could think of this as being the speed of the text animation, but in fact it doesn't work that way. This parameter sets the delay time between each separate character appearing, so lower number will produce faster animation. The default is 25. (Although "0" is quite legitimate, "10" is just about as fast as anyone could stand!) ParagraphDelay The length of the pause before the next paragraph begins to display, where lower numbers mean shorter pauses. The default is 500 (half a second). RepeatDelay The length of the pause before the ScriptFile or DefaultText is repeated. The default is 1500 (one-and-a-half seconds). Loop The number of times the ScriptFile (or DefaultText) should be shown. Any number is valid here, or you can enter the word infinite (not case-sensitive) to have the applet loop endlessly. Infinite looping is the default. Update When a remote text file has been specified in the ScriptFile parameter, NewsAgent will automatically check for a newer version of that file at regular intervals, and display that version instead. This parameter lets you specify that interval as a figure, in minutes. The default setting is 10 (ie. every 10 minutes). Sound Specifies whether or not you'd like NewsAgent to accompany the text animation with sound. A value of yes turns the sound option on, a value of no turns it off, and the values are not case sensitive. The default is no sound. See "Sounds" below. OnClick NewsAgent has two interactivity modes, which are the values for this parameter: hold or link. Neither value is case-sensitive. With the value set to hold, a mouse click will toggle the text animation between pause and resume, giving a reader a chance to catch up if the applet is moving faster than he'd like, or simply to pause for thought. With the value set to link, a single click will open the specified URL into the specified target frame or window, using the two parameters below. The default setting is hold. URL With the applet used in link mode (set in the OnClick parameter), this parameter becomes active. It specifies the relative or absolute URL of a web page or other resource that should be opened when the mouse is clicked within the applet area. (Note that if you use the applet in hold mode instead, there's no need to remove this parameter from your HTML page - it'll be ignored.) It's also worth noting that although Java does support #name anchors appended to URLs (to link to particular parts of a page), not all browsers will react correctly to it, so its use is generally best avoided. Target With the applet set to link mode, this parameter specifies the name of the frame or window into which the URL should be opened. The default is _top. (Note that if you use the applet in hold mode instead, there's no need to remove this parameter from your HTML page - it'll be ignored.) UseTooltips NewsAgent can optionally display tooltip messages within the applet area that move with the mouse. The simple values for this parameter are yes or no, and are not case-sensitive. The default is yes. When tooltips are used, what is displayed depends upon whether you've selected hold or link mode. In link mode, the tooltip message will be that chosen in the LinkMessage parameter. In hold mode, the tooltip message will switch between Click to pause and Click to resume, according to the applet's current status. TooltipColor A hex triplet that sets the color of the text used for the tooltip, and the color of the tooltip's outline. The default is 000000 (black). TooltipBgColor Another hex triplet setting the color of the tooltip's background (or fill). The default is 80FF80 (a sort of pale green type thing). LinkMessage If you use the applet in link mode, you can specify your own tooltip message that will appear when the mouse enters the applet area, and this is the parameter that lets you do it. The default is no message. Three audio files (.au format) are included in the zip archive. If you'd like NewsAgent to accompany text-display with sounds, place these three files in the same directory as the class file (ryNewsAgent.class) and set the value of the Sound parameter to Yes. If you prefer your pages to be seen and not heard, you have three options: you can set the parameter's value to No, remove the parameter entirely, or delete/remove the audio files. If you want to use only some of the sounds, set the parameter's value to Yes and just remove the files you don't want to use from that directory. For example, you might like the applet just to notify you when the ScriptFile has been updated, in which case you'd leave the Sound parameter set to Yes, but remove the TypeKey.au and TypeReturn.au files. The names of the three files are fixed: TypeKey.au plays when a character appears (ie. pretty frequently!). TypeReturn.au plays when the text is wrapped to the next line. Updated.au plays when a change to the contents of the ScriptFile has been detected (thus, of course, it will only ever play when you're using the ScriptFile parameter as opposed to the DefaultText parameter to specify your text). If you'd like to replace these with your own files, go right ahead. The only restrictions are that the files must be in Sun/NeXT format (.au), must be in the class directory (as noted by your codebase= attribute), and must use the filenames given above. If these sounds aren't to your taste, try the SoundPack for a whole bunch of extra choices. Just replace these files with the ones you want to use, making sure you rename the replacements as noted above. You can find the SoundPack at: www.btinternet.com/~ry/SoundPack Although NewsAgent may be freely used on any non-commercial pages, I'd appreciate an email containing the URL. I'd also appreciate a link back to the CodeBase site (URL below) so that visitors to your pages can find their own copy without having to email me, but it's not a condition of use. Rob rob.young@btinternet.com CodeBase http://www.btinternet.com/~ry/CodeBase
Java is a registered trademark of Sun Microsystems Inc. |