InfoWindow Class

Introduction

This guide describes the ReAction compatible InformationWindow.class for users and developers.

The latest version of the class is v53.6, available for both OS4 and OS3.

For Developers

TABLE OF CONTENTS

infowindow.class/--datasheet-- infowindow.class/IWM_OPEN

infowindow.class/--datasheet-- infowindow.class/--datasheet--

 NAME
   infowindow.class -- Create an information window

 SUPERCLASS
   window.class

 REQUIRES
   bitmap.image, button.gadget, checkbox.gadget, clicktab.gadget,
   label.image, layout.gadget, scroller.gadget, texteditor.gadget,
   window.class

 DESCRIPTION
   This is a BOOPSI class to create information windows, such as those that
   applications display when you select the "About" menu command.

   Supported features:

   - formatted text
   - image with configurable placement and backfill
   - configurable panel to display tabs, a scrollable text field, or a custom
     BOOPSI gadget (e.g. a listbrowser)
   - configurable button row supporting any number of buttons
   - optional checkbox gadget for confirming information
   - keyboard control
   - timeout

   The class does not replace the Requester Class but it can be seen as
   a more sophisticated version of the REQTYPE_INFO requester type.

 METHODS
   OM_NEW -- creates the infowindow object, sets attributes and defaults

   OM_SET -- sets object attributes (passed to the superclass first)

   OM_GET -- retrieves object attributes (passed to the superclass first)

   OM_DISPOSE -- disposes of the infowindow object

   IWM_OPEN -- opens the infowindow

 KEYBOARD CONTROL
   Escape
     Cancels the infowindow (IWM_OPEN returns IWMRES_CANCEL).

   Return / Enter
     Selects the default choice and closes the infowindow (IWM_OPEN returns
     the number of the button).

   Cursor Left / Right
     Switches between tabs (if the tab panel is displayed).

 ATTRIBUTES
   The infowindow is in fact a modal (i.e. blocking) requester, so all of its
   attributes can only be set or retrieved when the window is NOT open.

   Use SetAttrs() freely in between individual IWM_OPEN calls to re-configure
   the infowindow: no need to dispose of and rebuild the object if you want
   to change the look, contents or behaviour of the window.

   SetAttrs() will return the number of attributes set.

   The InfoWindow Class is based on the Window Class, so many attributes
   supported by the superclass are applicable. Use them wisely: make sure
   you don't turn the infowindow into something it's not supposed to be.

   The following superclass attributes are explicitly IGNORED because their
   (mis)use could compromise the look or functioning of the infowindow:

   WA_Backdrop
   WA_BackFill
   WA_Borderless
   WA_Hidden
   WINDOW_AppPort
   WINDOW_AppWindow
   WINDOW_Iconifiable
   WINDOW_IconifyGadget
   WINDOW_IDCMPHook
   WINDOW_InputEvent
   WINDOW_MenuStrip
   WINDOW_NewMenu
   WINDOW_PopupGadget

   Further notes on the use of superclass attributes:

   WA_Width and WA_Height are treated as WA_InnerWidth and WA_InnerHeight,
   respectively. This behaviour is inherited from the Window Class.

   If WA_CloseGadget is provided and set to TRUE, the IWM_OPEN method will
   return the value of IWMRES_CANCEL if the window was closed (= cancelled)
   via the close gadget. The Escape key shortcut has an identical function
   (and result value) but it is available at all times, regardless of the
   WA_CloseGadget setting.

   The class needs to be able to resolve the screen on which the infowindow
   will open. The following policy is applied here:
   - If INFOWINDOW_Parent is set, the class will attempt to obtain the screen
     pointer from the parent window object (the window needs to be open for
     this to work);
   - the WA_CustomScreen, WA_PubScreen and WA_PubScreenName tags are next in
     preference, respectively;
   - if there is no tag setting allowing to resolve the screen, it is assumed
     that opening on the default public screen is requested.

   You might prefer setting INFOWINDOW_Parent over the Intuition screen tags.
   This way the infowindow will always stay with your program window, which
   is especially useful if your application supports jumping between screens.
   Otherwise you'd have to update the infowindow with a new screen pointer
   whenever the application changes screen.

   The InfoWindow Class' own attributes are described below:

   INFOWINDOW_Parent (Object *)
     A pointer to a window object that will be the "parent" of the
     information window. Often the parent is the application's main window.
     The class will automatically set the busy pointer for the parent,
     blocking its input while the infowindow is open.

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_BodyText (CONST_STRPTR)
     Text for the body of the information window.

     The following codes can be used within the provided string to change
     the soft style of the text:

     ESC u -- underline
     ESC b -- bold
     ESC i -- italic
     ESC n -- normal

     Example string: "The following words \33bare in bold\33n."

     Defaults to NULL

     Applicability is (OM_NEW, OM_SET, OM_GET)

   INFOWINDOW_GadgetText (CONST_STRPTR)
     Text for the information window's button(s), delimited by the vertical
     bar character (|) if you want more than one button (e.g. "Yes|No").

     Defaults to "_OK"

     Applicability is (OM_NEW, OM_SET, OM_GET)

   INFOWINDOW_CheckBoxText (CONST_STRPTR)
     If you provide this text string, the class will display a checkbox
     gadget at the bottom of the information window. The string will become
     the gadget's label.

     One obvious purpose of the checkbox is to allow the user to confirm the
     information displayed in the window before closing it and proceeding.
     The state of the gadget upon closing the infowindow can be retrieved
     via the INFOWINDOW_Checked tag; see below.

     Defaults to NULL (no checkbox will be displayed)

     Applicability is (OM_NEW, OM_SET, OM_GET)

   INFOWINDOW_Checked (BOOL)
     Setting this attribute will make the checkbox selected or unselected
     when the infowindow next opens. GetAttrs() can be used to retrieve the
     state of the gadget upon closing the window.

     Please note that the class stores the checkbox state regardless of
     whether the infowindow was OK'ed, cancelled, or timed out. You'll want
     to also check the IWM_OPEN method return value to distinguish between
     these situations.

     Defaults to FALSE

     Applicability is (OM_NEW, OM_SET, OM_GET)

   INFOWINDOW_Justification (uint16)
     Body text justification. Applicable values are LJ_LEFT, LJ_CENTER
     or LJ_RIGHT.

     Defaults to LJ_LEFT (left-justified)

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_WrapBorder (uint16)
     If the body text does not contain any linefeeds (\n) it will be
     word-wrapped automatically after the number of characters specified
     in this tag.

     Defaults to 0 (no word-wrap)

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_DefButton (uint32)
     Specifies the default, highlighted button. If the Return or Enter key is
     pressed, the infowindow will close as if this button has been selected.
     A value of 0 means there is no default button, and the Return/Enter
     keyboard shortcut will not be available.

     Defaults to 1 (the first button from the left)

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_Image (Object *)
     A custom BOOPSI image object to display in the information window. Note
     that the image will not be disposed of by the class, you need to take
     care of this yourself (the logic here is: "you create the image, you
     dispose of it").

     This tag takes precedence over INFOWINDOW_ImageFile (see below).

     If your application supports jumping between different screens, it might
     be necessary to rebuild your custom image object for the particular new
     host screen, to ensure the image is rendered with proper colours. This
     will be the case when jumping between an 8-bit screen and a 16/32-bit
     screen, or vice versa.

     Defaults to NULL

     Applicability is (OM_NEW, OM_SET, OM_GET)

   INFOWINDOW_ImageFile (CONST_STRPTR)
     A name of a source file from which the class will create a BOOPSI image
     to display in the information window. The file can be in any picture
     format supported by DataTypes. The image object created this way is
     stored internally and the class will dispose of it automatically.

     This tag will be ignored if INFOWINDOW_Image is provided (see above).

     Defaults to NULL

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_ImagePlace (uint32)
     Flags to determine the placement of the image with regard to the body
     text. The image can be placed on the left (default), on the right,
     above or below the text. When PLACEIMAGE_ABOVE or PLACEIMAGE_BELOW is
     set, the image will be center-aligned horizontally unless you also set
     PLACEIMAGE_LEFT or PLACEIMAGE_RIGHT (for example, setting this tag to
     the combination of PLACEIMAGE_ABOVE|PLACEIMAGE_LEFT will display the
     image in the top-left corner above the body text).

     This tag will be ignored if there is no body text.

     Defaults to PLACEIMAGE_LEFT

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_ImageBackFill (struct Hook *)
     Sometimes it may be desirable to place the image on a filled background.
     This tag allows providing a backfill hook for this purpose.

     Defaults to NULL

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_TabPanel (struct InfoWindowTab *)
     Use this tag to configure a special panel for displaying additional
     information in the window. This will normally be a tabbed panel with
     scrollable text fields but other configurations are also possible.

     The tabbed panel is created by passing an array of struct InfoWindowTab
     (see <classes/infowindow.h> for definition). The Label member of each
     structure in the array must contain the tab label string. The actual
     contents of the Data member may vary depending on the Type member value:

     TABDATA_STRING -- Data contains a text string
     TABDATA_FILE   -- Data contains a name of a text file
     TABDATA_LOCK   -- Data contains a DOS lock on a text file

     This means that information to be displayed in the panel can be placed
     externally. For example, you can have a dedicated tab for displaying
     the program licence, the text of which is in a file on disk (only plain
     text files are supported at the moment):

     struct InfoWindowTab tabs[] =
      {
        { "Credits", (APTR) "This program was made by me!", TABDATA_STRING },
        { "Licence", (APTR) "PROGDIR:Docs/Licence.txt", TABDATA_FILE },
        { NULL, NULL, TABDATA_END }
      };

     Note that the array must be properly terminated as shown.

     If instead of an array you pass a single struct InfoWindowTab with
     a NULL Label member, a scrollable text field will be created in the
     place of the tabbed panel:

     struct InfoWindowTab textField =
      {
       NULL,
       (APTR) "PROGDIR:Docs/Licence.txt",
       TABDATA_FILE
      };

     The configuration can be further customized by using the TABDATA_GADGET
     value for Type. In such a case the Data member shall point to a BOOPSI
     gadget (for example, a listbrowser):

     struct InfoWindowTab customPanel =
      {
       NULL,
       (APTR) myListBrowser,
       TABDATA_GADGET
      };

     The configuration above will display your own listbrowser gadget
     instead of the panel, and this

     struct InfoWindowTab tabs[] =
      {
        { "Credits", (APTR) myListBrowser, TABDATA_GADGET },
        { "Licence", (APTR) "PROGDIR:Docs/Licence.txt", TABDATA_FILE },
        { NULL, NULL, TABDATA_END }
      };

     will show your listbrowser under the "Credits" tab instead of the
     standard text field.

     The tab panel's text fields are currently rendered using the Texteditor
     Gadget. This may change in the future.

     Defaults to NULL (no panel)

     Applicability is (OM_NEW, OM_SET)

   INFOWINDOW_TimeOut (uint32)
     The displayed information window will time out and close after the
     number of seconds specified via this tag. The IWM_OPEN method will
     return with a result of IWMRES_TIMEOUT.

     Defaults to 0 (no timeout)

     Applicability is (OM_NEW, OM_SET)

 NOTES
   The timeout feature is currently implemented with IntuiTicks, so the
   internal countdown will stop when the infowindow becomes inactive.
   This needs to be reimplemented using timer.device.

 BUGS

 SEE ALSO
   

infowindow.class/IWM_OPEN infowindow.class/IWM_OPEN

 NAME
   IWM_OPEN -- Open the information window

 SYNOPSIS
   int32 result = IDoMethodA(APTR obj, Msg msg);
   int32 result = IDoMethod(APTR obj, IWM_OPEN, NULL);

 FUNCTION
   Opens the information window.

 INPUTS
   obj - an infowindow object pointer
   msg - a Msg with MethodID = IWM_OPEN (see <intuition/classusr.h>)

 RESULT
   The number of the button (1, 2, 3...) the user has selected.
   IWMRES_ERROR if the information window failed to open for some reason.
   IWMRES_CANCEL if the window was closed via the close gadget or Esc key.
   IWMRES_TIMEOUT if the window has timed out.

 EXAMPLE
   
 NOTES

 BUGS
   
 SEE ALSO