HyperBook control numpages num = NUMPAGES () Return the number of pages in the current hyperbook. hyperbookname name = HYPERBOOKNAME () Return the name (i.e. the full path name) of the current hyperbook. loadhyperbook bool (0 or 1) = LOADHYPERBOOK (filename) Load the specified hyperbook. savehyperbook bool (0 or 1) = SAVEHYPERBOOK (filename) Save the current hyperbook under the given name. hyperbooktofront HYPERBOOKTOFRONT () Bring the HyperBook screen to the front. hyperbooktoback HYPERBOOKTOBACK () Push the HyperBook screen to the back. quithyperbook QUITHYPERBOOK () Exit the HyperBook program. Navigation nextpage NEXTPAGE () Equivalent to the right arrow gadget on the main control panel. prevpage PREVPAGE () Equivalent to the left arrow gadget on the main control panel. gotopage old = GOTOPAGE (new) Go to the page whose objnum is new; return the objnum of the departed page. callpage old = CALLPAGE (new) Go to the given new page, and return the objnum of the departed page. A subsequent RETURN will go back to the departed page. return newpage = RETURN () Make current the last page called (from Table of Contents, CALLPAGE, etc.), and return the objnum of that page. Main control panel bigpanel BIGPANEL () Put the main control panel into its `big' state. tinypanel TINYPANEL () Put the main control panel into its `tiny' state. controlpanel CONTROLPANEL (bool) Close (arg = 0) or open (arg = 1) the main control panel. General editing delete DELETE (arg) Delete a page, object or item, or empty the bin. relocate new = RELOCATE (arg, newparent) Move the given object to the bin, a page or a group; or the given item to a new list. Return the new objnum of the object or item moved. getbackground color = GETBACKGROUND (arg) Return the background color number of a page or object (-1 is returned for transparent object backgrounds). setbackground oldcolor = SETBACKGROUND (arg, newcolor) Set the background color of a page or object, and return the old color. The object transparent `color' is -1. getwidth width = GETWIDTH (arg) Return the width in pixels of the given page or object. getheight width = GETHEIGHT (arg) Return the height in scan-lines of the given page or object. getname name = GETNAME (arg) Return the name of a page or object. setname oldname = SETNAME (arg, newname) Set the name of the given page or object, and return the previous name. Page Creation createpage page = CREATEPAGE (frompage, number) Create a new page with the given page number using the page specified by the frompage objnum as a template. The new page is a clone of frompage but does not have any objects on it. Giving zero as the page number causes the new page to be appended to the hyperbook. Return the objnum of the new page. clonepage page = CLONEPAGE (frompage, number) Create a new page with the given page number using the page specified by the frompage objnum as a template. The new page is a clone of frompage, including any objects on it. Giving zero as the page number causes the new page to be appended to the hyperbook. Return the objnum of the new page. mastertopage page = MASTERTOPAGE(name, pos) A new page is created at position pos from the given master page. The objnum of the new page is returned. Master pages pagetomaster PAGETOMASTER (page, name) Clone the specified page, including any objects on it, and add it to the master page list under the given name. ismasterpage bool = ISMASTERPAGE (name) Return TRUE (1) if the given name is that of an existing master page. deletemaster DELETEMASTER (name) Delete the master page of the given name. Page files loadpage page = LOADPAGE (file, num) Load the specified file as page num, and return the objnum of the newly-loaded page. A page number of 0 loads to the last page. mergepage MERGEPAGE (parg, file) Merge the objects in the specified page file onto the page whose objnum is parg. savepage SAVEPAGE (parg, file) Save the specified page to the named file. Page editing getpagelace bool (1 or 0) = GETPAGELACE (page) Returns 1 if the given page is in interlace mode, otherwise 0. setpagelace bool (1 or 0) = SETPAGELACE (page, bool) Set the current page to interlace on (bool argument 1) or off (bool argument 0). Return the previous interlace state. getpagecolors count = GETPAGECOLORS (page) Return the number of colors in the palette of the given page. setpagecolors oldcount = SETPAGECOLORS (arg, count) Set the number of colors (normalized to 4, 8 or 16) for the current page's palette, and return the old count. getpagergb rgb = GETPAGERGB (page, reg) Return the packed rgb value of color register reg on the given page. setpagergb oldrgb = SETPAGERGB (page, reg, rgb) Set the color register reg on the given page to the new rgb value, and return the old value of that register. wiperoutine old = WIPEROUTINE (page, new) Get/set the wipe effect used by the given page. Values for new in the range 0 to 17 will change the page effect as per the list at right; other values (e.g. -1) do not select a new effect. pagedim old = PAGEDIM (page, new) Get/set the screen dimming effect that precedes the wipe effect for the given page, and return the previous setting. A new value of 0 turns dimming off; 1 turns it on. Other values (e.g. -1) do not change the current setting. setpagenumber new = SETPAGENUMBER (page, num) Resequence the page whose position is num, and return its new objnum. refreshpage REFRESHPAGE () Redraw the current page. Object creation createnote note = CREATENOTE () Create an empty note of size 61x23 and position (0,0) in the bin, using the current default note attributes, and return its objnum. createbutton button = CREATEBUTTON () Create an empty button of size 33x17 and position (0,0) in the bin, using the current default button attributes, and return its objnum. createlist list = CREATELIST () Create an empty list of size 65x43 and position (0,0) in the bin, using the current default list attributes, and return its objnum. creategroup group = CREATEGROUP () Create an empty group object in the bin, and return its objnum. clone new = CLONE (arg, newparent) Clone the given object to the bin, a page or a group; or the given item to a new list. Arg is unchanged. Return the clone's objnum. Object editing getleft left = GETLEFT (obj) Return the left edge position of the object, measured in pixels from the left edge of its page. gettop top = GETTOP (obj) Return the top edge position of the object, measured in scan-lines from the top edge of its page. setposition SETPOSITION (obj, x, y) Set the left and top co-ordinates of the given object. getborder border = GETBORDER (obj) Return the border color of the object, or -1 if the object's border is transparent. setborder oldcolor = SETBORDER (obj, color) Set the border of the object to the given color, and return the previous color. The transparent `color' is -1. getshadow shadow = GETSHADOW (obj) Return the shadow color of the object, or -1 if the object's shadow is transparent. setshadow oldcolor = SETSHADOW (obj, color) Set the shadow of the object to the given color, and return the previous color. The transparent `color' is -1. shadowstyle old = SHADOWSTYLE (obj, style) Get/set the style of shadow used by obj. The available styles are drop-shadow (style = 1) and embossed (2). Any other value (e.g. 0) doesn't change the current shadow style setting. getvisibility bool (1 or 0) = GETVISIBILITY (obj) Return 1 if the `natural visibility state' of the object is visible, or 0 if it is invisible. setvisibility bool (1 or 0) = SETVISIBILITY (obj, state) Set the `natural visibility state' of the object to visible (1), or invisible (0). Return the previous state. scale SCALE (obj, percent) Scale the object's width and height to the given percentage of its current dimensions. scaletosize SCALETOSIZE (obj, width, height) Scale the object to the given width and height. objecttoback objnum = OBJECTTOBACK (obj) Bring the given object to the back of its group/page and return its new objnum. objecttofront objnum = OBJECTTOFRONT (obj) Bring the given object to the front of its group/page and return its new objnum. getgroupdepth depth = GETGROUPDEPTH (obj) Return the grouping depth of the given object, starting with 0 if the object is not in a group. explode firstobj = EXPLODE (group) Explode the given group, and insert its constituent objects in the group's place in its parent list. Return the objnum of the first of these objects (or the empty string if the group had no objects). Actions getaction action = GETACTION (arg) Return the action type associated with the given object or item, one of: noaction, gopage, showpic, showhide, displaytext, doscommand, rexxcommand or rexxmacro. getactiontext action = GETACTIONTEXT (arg) Return the text associated with the given object or item's action. setactionnone oldact = SETACTIONNONE (arg) Set the action of the specified object or item to noaction. Return the type of the former action. setactionpage oldact = SETACTIONPAGE (arg, parg) Set the action of the specified object or item to gopage. The page's objnum is parg. Return the type of the former action. setactionpic oldact = SETACTIONPIC (arg, name) Set the action of the specified object or item to showpic. The picture is the ILBM file name. Return the type of the former action. setactionshow oldact = SETACTIONSHOW (arg, oarg) Set the action of the specified object or item to showhide. The objnum of the target object is oarg. Return the type of the former action. setactionread oldact = SETACTIONREAD (arg, name) Set the action of the specified object or item to displaytext. The text is in the file name. Return the type of the former action. setactiondos oldact = SETACTIONDOS (arg, cmd) Set the action of the specified object or item to doscommand. The command is the string cmd. Return the type of the former action. setactionrexx oldact = SETACTIONREXX (arg, dos) Set the action of the specified object or item to rexxcommand. The command is the string cmd. Return the type of the former action. setactionmacro oldact = SETACTIONMACRO (arg, marg) Set the action of the specified object or item to rexxmacro. The named macro (marg) is used. Return the type of the former action. setactionlink oldact = SETACTIONLINK (arg, linktype) Set the action of the specified object or item to one of the special variants of the gopage action: nextpage, prevpage, firstpage, lastpage, return or selectpage. Return the type of the former action. activate ACTIVATE (object) Execute the action for the given object or item as though it had been clicked on. Note and button text readnotetext str = READNOTETEXT (arg, pos, amt) Return a string consisting of amt characters beginning at pos in the given note or button. An amt of -1 means `to the end of text'. inserttext INSERTTEXT (arg, text, pos) Insert text at pos in the given note or button. If pos is -1, the text is appended. replacetext oldtext = REPLACETEXT (arg, text, pos, amt) The new text replaces amt characters, beginning at pos in the given note or button. An amt of -1 means `to the end of text'. cleartext CLEARTEXT (arg) Remove all the text from the given note or button. deletetext oldtext = DELETETEXT (note, pos, amt) Delete amt characters beginning at pos in the given note or button, and return the deleted text. An amt of -1 means `to the end of text'. Items and lists getitemcolor color = GETITEMCOLOR (item) Return the color of the given item. setitemcolor old = SETITEMCOLOR (item, color) Set the color of the given item, and return its previous color. getitemtext text = GETITEMTEXT (item) Return the text string associated with the given item. setitemtext oldtext = SETITEMTEXT (item, text) Set the item text to text, and return the former text. insertitem item = INSERTITEM (next, text, color) Create a new item with the given color and text, inserted before item next in its list, and return the objnum of the new item. appenditem item = APPENDITEM (list, text, color) Create a new item with the given color and text, append it to the given list, and return its objnum. moveitem item = MOVEITEM (olditem, pos) Move the given item within its list to position pos, and return its new objnum. clearlist CLEARLIST (list) Empty the given list of all items. sortlist SORTLIST (list1 [,list2, ..., listn]) Sort the items in the given list in ascending lexical order. If more than one list is given, the first is sorted, and the others are re-ordered in the same way as list1. All the lists must have the same number of items. refreshlist REFRESHLIST (list) Redraw the given list. Use this to force a refresh while the INTERACTIVE flag is turned off (which normally suppresses list rendering). listscroll LISTSCROLL (item) Scroll the given item's list so that the item is at the top, or as near as possible to the top, of the list's display area. listheight count = LISTHEIGHT (list) Return the number of items the given list can display at its current size. The list does not necessarily contain this many items. Searches searchstart SEARCHSTART (start) Set the default starting point for SEARCHNAME, SEARCHPAGENAME and SEARCHTEXT. If start is an objnum, set the starting point to the corresponding page and object (if the objnum is that of a page or the bin, the object is taken to be the first in the relevant object list). An empty start string is equivalent to specifying '1:' - the first page. searchname obj = SEARCHNAME (start, substr) From the given starting point in the hyperbook, search for an object whose name contains substr, and return its objnum (the empty string if not found). If the start argument is empty, the search begins where the most recent search left off, or at the point set by SEARCHSTART. The search is case insensitive. searchpagename obj = SEARCHPAGENAME (start, substr) From the given starting point in the hyperbook, search for a page whose name contains substr, and return its objnum (the empty string if not found). If the start argument is the empty string, the search begins where the most recent search left off, or at the point set by SEARCHSTART. The search is case insensitive. searchtext obj = SEARCHTEXT (start, substr) From the given starting point in the hyperbook, search for an object or list whose text contains substr, and return its objnum (the empty string if not found). If start is the empty string, the search begins where the most recent search left off, or as set by SEARCHSTART. The search is case insensitive. searchitems item = SEARCHITEMS (arg, text) Search a list (from the beginning, if arg is a list; or from the given item) for text, and return either the objnum of the item containing the text or, if the search failed, the empty string. The search is case insensitive. searchnote pos = SEARCHNOTE (arg, pattern, start) Search the given note or button, arg, starting at position start, for the string pattern, and return the position at which it is found, or -1 if the search fails. The search is case insensitive. User input getresponse bool (1 or 0) = GETRESPONSE (prompt) Put up the Okay/Cancel requester with the given prompt string. Return 1 if the user clicks Okay (the checkmark), 0 for Cancel (the X). inputstring str = INPUTSTRING (prompt, default) Prompt the user to enter a string (modifying the given text, if default is non-empty) and return it. Note: the empty string is returned if the user cancels the requester. inputform text = INPUTFORM (prompt, formtext) Obtain multiple lines of input from the user. Formtext specifies the label and the default string for each input line in this format: