Module: Hypertext 1.30, by SSH
Display marked-up text, including hyperlinks
Download Hypertext as a zip file
Author
Andrew MacCormack (SSH)
Please use the messaging function on the AGS forums to contact
me about problems with this module
Abstract
Display text with different fonts, colours, etc. changing in
the middle of the text with proprietary markup. Also does
hyperlinking to allow a web-like interface.
Dependencies
AGS 2.72 or later
Functions
function Hypertext.SetPrefixStyle(char prefix, int font, optional HypertextSpecialT special,
optional int r, optional int g, optional int b,
optional int bgr, optional int bgg, optional int bgb);
SetPrefixStyle allows you to set the way text is printed according to markup.
You can use any character you like as a markup character, but you should avoid
characters that you are likely to use at the beginning or end of words in the
normal course of events. Some possibilities are ^_*{}+=@~#/<>\| but it depends
on your game. By default, _*+ are set up. _ has a special meaning of indicating
a link, also.
The font arguments is the AGS font number to use. If you can, use proper, separate
fonts for bold, italic versions, but if you can't you can set the 'special'
argument to fake bold and italic for you. The italic effect is not great, though!
The special argument can also be used to overline, underline, strikethrough,
cross-out or box each word.
The r, g and b arguments let you set the text colour. Similarly, bgr, brg, brb let
you set the background colour. If any arguments are omitted, no change is made to
that aspect of the text's appearance.
The special prefix arguments HYPERTEXT_NORMAL and HYPERTEXT_VISITED are for setting
the style of default text and visited links.
function Hypertext.DisablePrefix(char prefix);
Disables an already-defined markup character.
function Hypertext.Add(String Title, String Text);
Add a hypertext page called Title with data Text. If a Title already exists, appends
the text to the end of the existing page.
function Hypertext.Prerender();
Once you have set up all your hypertext pages, running this before any page is shown
can make sure that the visited links are shown correctly.
function Hypertext.ShowOnBG(String Title);
function Hypertext.RestoreBG();
If you want the Hypertext to be shown on the Room background, use the ShowOnBG
function and the name of the first page to view. When finished, call RestoreBG.
function Hypertext.ShowOnGUI(GUI *where, String Title);
This function shows the Hypertext page specified on the GUI (as background image)
function Hypertext.ShowOnButton(Button *where, String Title);
This function shows the Hypertext page specified on the given GUI button
function Hypertext.ShowOnOverlay(int x, int y, int width, String Title);
This function show the Hypertext page specified on an Overlay at x, y of width
specified.
function Hypertext.Show(String Title);
This function shows the given page using the method already selected with one of
the above ShowOnXXX functions.
function Hypertext.Last();
This function goes back to the previous page in the history, like a browser's
Back button.
function Hypertext.SpeechStyle(eSpeechStyle style, optional int y);
If you are using Sierra-style speech, you must use this function to set the style.
Lucasarts-style is the default. The other styles are not supported. You can also set
the Y position of the text for Sierra speech only. Default is 18.
function Hypertext.Say(Character *who, String what);
Works like the character.Say command, but does Hypertext. Automatically uses the
MultiResponse module if it is installed previously in the module manager.
function Hypertext.Disp(String what);
Works like the Display function, except no printf-style formatting is done. Use
String.Format inside the brackets if you want that functionality.
function Hypertext.SetBubbleColour(int r, int g, int b, int bgr, int bgg, int bgb);
Set the border and background colours of speech bubbles. This does not, however,
enable the bubbles.
function Hypertext.SetDispColour(int r, int g, int b, int bgr, int bgg, int bgb);
Set the border and background colours of Hypertext.Disp boxes.
function Hypertext.SetBubble(int xmargin, int ymargin, int circle, optional int tailheight,
optional int tail1, optional int tail2);
Enable speech bubbles, and set the margins between the border and the text, the
radius of the circles at the ends of the box (set to -1 for diameter=bubble height),
the height of the tail, if one is wanted (default 0, meaning no tail), and the
2 X offsets of the wide part of the tail. Set both to the same to have a single-line
tail.
function Hypertext.NoBubble();
Turn off speech bubbles that have perviously been enabled with SetBubble;
Configuration
To increase the number of pages, alter HYPERTEXT_MAX_PAGES below. To have more
links on any one page, increase HYPERTEXT_MAX_LINKS. Blank lines have a height of
HYPERTEXT_MIN_LINE_HEIGHT, which can also be used to set general line spacing.
The special character used for links can be changed with HYPERTEXT_LINK and
the "pipe" character used to link to a page of a different name can be changed
with HYPERTEXT_PIPE. It is not recommended to change any other #defines.
Unless you are just drawing on the background, do not turn TTF antialiasing on.
your text will all have a pink border if you do...
Example
// Set the = prefix to use font 8, underlined, blue
Hypertext.SetPrefixStyle('=', 8, true, 0, 0, 255);
Hypertext.Add("page1", "=Hypertext=[Click on this link to go to _page2_");
Hypertext.Add("page2", "You can try _page1_ or _page3|another page_ now");
Hypertext.Add("page3", "=Dead end=[This page has no links!");
Hypertext.ShowOnButton(goPDA, "page1");
Caveats
Italic effect is rubbish
"Specials" operate over the space before a word sometimes, too
Lots todo, see todo list below.
Revision History
8 Dec 06: v1.0 First release of Hypertext module
11 Dec 06: v1.1 Added Say, Display functions and more specials
14 Dec 06: v1.2 Fixed some bugs, added speech bubbles
16 Feb 07: v1.21 Fixed GUI Clickable bug
11 Mar 08: v1.3 Support AGS 3.0
Licence
Hypertext AGS script module
Copyright (C) 2006, 2007, 2008 Andrew MacCormack
This module is licenced under the Creative Commons Attribution Share-alike
licence, (see http://creativecommons.org/licenses/by-sa/2.5/scotland/ )
which basically means do what you like as long as you credit me and don't
start selling modified copies of this module.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
In addition to the licences mentioned in the modules themselves, you may choose to use the following creative commons licence if you prefer for all AGS modules and open source code resources on my site.
This work is licenced under a Creative Commons Licence.