src/motif/mdi/doc/mwindow.html

   1 <HTML>
   2
   3 <HEAD>
   4 <TITLE>XsMotifWindow Class</TITLE>
   5 <LINK REV="made" HREF="mailto:ssadler@cisco.com">
   6 </HEAD>
   7
   8 <H2>
   9 The XsMotifWindow Class
  10 </H2>
  11
  12 <P>
  13 The <I>XsMDICanvas</I> requires that all documents be a subclass of
  14 <I>XsMDIWindow</I> or a subclass of a class derived from it.  By itself
  15 <I>XsMDIWindow</I> does not define any appearance or behavior for the
  16 documents.  However, <I>XsMotifWindow</I>, derived from <I>XsMDIWindow</I>,
  17 defines a MWM-like look-and-feel to a document.
  18
  19 <P>
  20 Documents in your application should be derived from <I>XsMotifWindow</I>.
  21 This class provides the look-and-feel of Motif window and supports the
  22 interaction with the <I>XsMDICanvas</I>.  It is up to the application to
  23 define the contents of each document.
  24
  25 <P>
  26 <B>Constructor and Destructor:</B>
  27
  28 <P>
  29 The <I>XsMotifWindow</I> constructor accepts one argument:
  30
  31 <DL>
  32 <DD>XsMotifWindow (const char *name)</DD>
  33 </DL>
  34
  35 <P>
  36 The <I>name</I> parameter specifies the name of the document and is used
  37 as the widget name for the underlying implementation.  The name parameter
  38 is also used as the default title and icon-name for the document.
  39
  40 <P>
  41 <B>Note:</B>  The <I>XsMotifWindow</I> constructor does not create any
  42 widgets.  Rather it only initializes internal variables.  The widgets are
  43 not created until the document is added to the canvas.  The <I>XsMDICanvas</I>
  44 calls the member-function <I>XsMotifWindow::_buildClientArea()</I> when it needs
  45 to create the document widgets.
  46
  47 <P>
  48 The <I>XsMotifWindow</I> destructor destroys the document widgets (if they have
  49 been created) and frees its internal storage.  It is up to the application
  50 to free all documents.  The <I>XsMDICanvas</I> will <B>not</B> destroy the
  51 documents for you.
  52
  53 <P>
  54 <B>Document Utilities:</B>
  55
  56 <P>
  57 Although rarely called from the application, the <I>XsMotifWindow</I> supports
  58 a number of utility functions to manipulate the document.
  59
  60 <DL>
  61 <DD>virtual void raise ( )</DD>
  62 <DD>virtual void lower ( )</DD>
  63 <DD>virtual void minimize ( )</DD>
  64 <DD>virtual void maximize ( )</DD>
  65 <DD>virtual void restore ( )</DD>
  66 <DD>virtual void close ( )</DD>
  67 </DL>
  68
  69 <P>
  70 The <I>close</I> member-function does not destroy the document, it simply
  71 hides it from view.  You can restore a closed document with
  72 <I>XsMotifWindow::show()</I>.
  73
  74 <P>
  75 The following member-functions are used to change/query the appearance of
  76 the document:
  77
  78 <DL>
  79 <DD>void  setTitle (const char *name)</DD>
  80 <DD>const char *title ( ) const</DD>
  81 <DD>void  setIconName (const char *name)</DD>
  82 <DD>const char *iconName ( ) const</DD>
  83 <DD>void  setPixmap (Pixmap pixmap)</DD>
  84 <DD>Pixmap pixmap ( ) const</DD>
  85 <DD>Widget icon ( ) const</DD>
  86 <DD>Boolean minimized ( ) const</DD>
  87 <DD>Boolean  maximized ( ) const</DD>
  88 <DD>virtual void setPosition (Position x, Position y)</DD>
  89 <DD>virtual void setSize (Dimension width, Dimension height)</DD>
  90 </DL>
  91
  92 <P>
  93 The <I>setPixmap</I> member-function accepts a pixmap which the document then
  94 uses as the decoration on the icon.  Because the document does not make a copy
  95 of the pixmap, it is important that the application not free the pixmap until
  96 all documents that reference it are deleted.  The document does, however, make
  97 a local copy of the title or icon-name string passed to it, so the application
  98 is free to do whatever it wants to the passed-in string.  The <I>icon</I>
  99 member-function returns the widget that is used to implement the icon.
 100
 101
 102 <P>
 103 <B>Creating Window Subclasses:</B>
 104
 105 <P>
 106 The application must derive its documents from <I>XsMotifWindow</I> in order to
 107 define the contents of the document.  The <I>XsMDICanvas</I> calls the
 108 protected member-function <I>_buildClientArea</I> when it creates the
 109 document. Each class derived from <I>XsMotifWindow</I> <B>must</B> override
 110 this pure-virtual member-function.
 111
 112 <P>
 113 The member-function <I>_buildClientArea</I> is called with a single argument:
 114
 115 <DL>
 116 <DD>virtual void _buildClientArea (Widget parent)</DD>
 117 </DL>
 118
 119 The <I>parent</I> argument should be used as the parent of the contents of
 120 the document.  This widget is an unmanaged <I>XmForm</I> widget, and all of
 121 the standard resources and constrains apply to it.  The <I>XsMDICanvas</I>
 122 is responsible for managing the parent widget at the appropriate time.
 123
 124 <P>
 125 As an example, consider the following:
 126
 127 <PRE>
 128 // _buildClientArea (called to create document contents)
 129
 130 void MyDocument::_buildClientArea (Widget parent)
 131 {
 132    assert (parent != 0);
 133
 134 // Create a main window with some dummy menus
 135
 136    Widget mainW = XtVaCreateWidget ("mainWin", xmMainWindowWidgetClass, parent,
 137       XmNtopAttachment, XmATTACH_FORM, XmNbottomAttachment, XmATTACH_FORM,
 138       XmNleftAttachment, XmATTACH_FORM, XmNrightAttachment, XmATTACH_FORM,
 139       NULL);
 140    ...
 141
 142    XtManageChild (mainW);
 143 }
 144 </PRE>
 145
 146 <P>
 147 In this case, an <I>XmMainWindow</I> is created as the child of the parent
 148 widget.  The <I>XmMainWindow</I> is then attached to the 4 sides of the parent
 149 form.  Note also that the main window is managed before returning from the
 150 function.
 151
 152 <P>
 153 <B>Resources:</B>
 154
 155 <P>
 156 The <I>XsMotifWindow</I> supports the following resources:
 157
 158 <PRE>
 159    Name              Class             Type           Default
 160 ------------------------------------------------------------------------------
 161    borderSize        BorderSize        Dimension      6
 162    buttonSize        ButtonSize        Dimension      23
 163    title             Title             String         dynamic
 164    titleFont         TitleFont         String         -*-helvetica-bold-o-normal-*-14-*-*-*-*-*-iso8859-1
 165    iconSize          IconSize          Dimension      70
 166    iconName          IconName          String         dynamic
 167    iconFont          IconFont          String         *-helvetica-bold-r-normal-*-12-*-*-*-*-*-iso8859-1
 168    XmNiconX          XmCIconX          Position       dynamic
 169    XmNiconY          XmCIconY          Position       dynamic
 170    saveUnder         SaveUnder         Boolean        True
 171    restoreString     RestoreString     String         "Restore"
 172    moveString        MoveString        String         "Move"
 173    sizeString        SizeString        String         "Size"
 174    minimizeString    MinimizeString    String         "Minimize"
 175    maximizeString    MaximizeString    String         "Maximize"
 176    raiseString       RaiseString       String         "Raise"
 177    lowerString       LowerString       String         "Lower"
 178    closeString       CloseString       String         "Close"
 179    menuFont          MenuFont          String         -*-helvetica-bold-o-normal-*-14-*-*-*-*-*-iso8859-1
 180    showBorder        ShowBorder        Boolean        True
 181    showResize        ShowResize        Boolean        True
 182    showTitle         ShowTitle         Boolean        True
 183    showMenu          ShowMenu          Boolean        True
 184    showMinimize      ShowMinimize      Boolean        True
 185    showMaximize      ShowMaximize      Boolean        True
 186    lowerOnIconify    LowerOnIconify    Boolean        False
 187    XmNminWidth       XmCMinWidth       Dimension      dynamic
 188    XmNmaxWidth       XmCMaxWidth       Dimension      dynamic
 189    XmNminHeight      XmCMinHeight      Dimension      dynamic
 190    XmNmaxHeight      XmCMaxHeight      Dimension      dynamic
 191 </PRE>
 192
 193 <DL>
 194 <DD>
 195 <DL>
 196 <DT>borderSize</DT>
 197 <DD>Size of the window border.</DD>
 198 <DT>buttonSize</DT>
 199 <DD>Size of the window buttons.</DD>
 200 <DT>title</DT>
 201 <DD>Title of the window.  The default is the name of the window instance.</DD>
 202 <DT>titleFont</DT>
 203 <DD>Font used to draw the window title.</DD>
 204 <DT>iconSize</DT>
 205 <DD>Size of the icon representation.</DD>
 206 <DT>iconName</DT>
 207 <DD>String used on the title.  If unspecified, the window title is used.</DD>
 208 <DT>iconFont</DT>
 209 <DD>Font used to draw the icon-name.</DD>
 210 <DT>XmNiconX</DT>
 211 <DD>X-position of the icon.  The default location is the top-left
 212 corner of the window when it is iconified.</DD>
 213 <DT>XmNiconY</DT>
 214 <DD>Y-position of the icon.  The default location is the top-left
 215 corner of the window when it is iconified.</DD>
 216 <DT>saveUnder</DT>
 217 <DD>Enables/Disables save-unders for the menu.</DD>
 218 <DT>restoreString</DT>
 219 <DD>String used as the "restore" menu item.</DD>
 220 <DT>moveString</DT>
 221 <DD>String used as the "move" menu item.</DD>
 222 <DT>sizeString</DT>
 223 <DD>String used as the "size" menu item.</DD>
 224 <DT>minimizeString</DT>
 225 <DD>String used as the "minimize" menu item.</DD>
 226 <DT>maximizeString</DT>
 227 <DD>String used as the "maximize" menu item.</DD>
 228 <DT>raiseString</DT>
 229 <DD>String used as the "raise" menu item.</DD>
 230 <DT>lowerString</DT>
 231 <DD>String used as the "lower" menu item.</DD>
 232 <DT>closeString</DT>
 233 <DD>String used as the "close" menu item.</DD>
 234 <DT>menuFont</DT>
 235 <DD>Font used to draw the menu strings.</DD>
 236 <DT>showBorder</DT>
 237 <DD>Enables/Disables the window border.  If the border is disabled,
 238 the resize-handles are automatically disabled.</DD>
 239 <DT>showResize</DT>
 240 <DD>Enables/Disables the window resize handles.</DD>
 241 <DT>showTitle</DT>
 242 <DD>Enables/Disables the window title.  If the title is disabled,
 243 all of the window buttons are automatically disabled.</DD>
 244 <DT>showMenu</DT>
 245 <DD>Enables/Disables the window menu button.</DD>
 246 <DT>showMinimize</DT>
 247 <DD>Enables/Disables the window minimize button.</DD>
 248 <DT>showMaximize</DT>
 249 <DD>Enables/Disables the window maximize button.</DD>
 250 <DT>lowerOnIconify</DT>
 251 <DD>Automatically lower windows when iconified.</DD>
 252 <DT>XmNminWidth</DT>
 253 <DD>Minimium window width.  The default is about four times the size of
 254 the window button.</DD>
 255 <DT>XmNmaxWidth</DT>
 256 <DD>Maximum window width.  The default is not to constrain the maximum size.</DD>
 257 <DT>XmNminHeight</DT>
 258 <DD>Minimum window height.  The default is about four times the size of
 259 the window button.</DD>
 260 <DT>XmNmaxHeight</DT>
 261 <DD>Maximum window height.  The default is not to constrain the maximum size.</DD>
 262 </DL>
 263 </DD>
 264 </DL>
 265
 266 <P>
 267 <B>XsMotifWindow Implementation:</B>
 268
 269 <P>
 270 As a convenience to those who wish to modify the <I>XsMotifWindow</I> code,
 271 here is a diagram of the internal class structure:
 272
 273 <P>
 274 <IMG SRC="pics/winclass.gif" ALT="[Class Structure]">
 275
 276 </BODY>
 277 </HTML>