src/motif/mdi/doc/canvas.html

   1 <HTML>
   2
   3 <HEAD>
   4 <TITLE>XsMDICanvas Class</TITLE>
   5 <LINK REV="made" HREF="mailto:ssadler@cisco.com">
   6 </HEAD>
   7
   8 <H2>
   9 The XsMDICanvas Class
  10 </H2>
  11
  12 <P>
  13 This section describes how to build and manipulate an MDI using the
  14 <I>XsMDICanvas</I> class.  Minimally, you must perform the following actions
  15 to build and display an MDI canvas:
  16
  17 <OL>
  18 <LI>Create the <I>XsMDICanvas</I> object.</LI>
  19 <LI>Create the documents as instances of subclasses of <I>XsMDIWindow</I>.</LI>
  20 <LI>Add the documents to the canvas</LI>
  21 <LI>Show the canvas</LI>
  22 </OL>
  23
  24 <P>
  25 <B>Constructor and Destructor:</B>
  26
  27 <P>
  28 The <I>XsMDICanvas</I> accepts two arguments:
  29
  30 <DL>
  31 <DD>XsMDICanvas (const char *name, Widget parent)</DD>
  32 </DL>
  33
  34 <P>
  35 The <I>name</I> parameter specifies the name of the canvas and is used
  36 as the widget name for the underlying implementation.  The <I>parent</I>
  37 parameter specifies the widget that is to be used as the parent of the
  38 canvas.
  39
  40 <P>
  41 The <I>XsMDICanvas</I> destructor destroys the canvas, but it <B>does not</B>
  42 destroy any of the underlying documents.  It is up to the application to
  43 destroy these.
  44
  45 <P>
  46 <B>Adding and removing documents:</B>
  47
  48 <P>
  49 After the documents are created, they must be added to the canvas.  The
  50 <I>XsMDICanvas::add()</I> member-function adds documents to the canvas:
  51
  52 <DL>
  53 <DD>virtual void add (XsMDIWindow *window)</DD>
  54 </DL>
  55
  56 <P>
  57 The behaviour of adding the same document to the canvas more than once
  58 is undefined.  Documents can be removed from the canvas by using:
  59
  60 <DL>
  61 <DD>virtual void remove (XsMDIWindow *window)</DD>
  62 </DL>
  63
  64 <P>
  65 Additionally, all documents can be removed from the canvas with:
  66
  67 <DL>
  68 <DD>void removeAll ( )</DD>
  69 </DL>
  70
  71 <P>
  72 The number of documents currently installed in the canvas can be
  73 retrieved with:
  74
  75 <DL>
  76 <DD>int numWindows ( ) const</DD>
  77 </DL>
  78
  79 <P>
  80 <B>Showing the canvas:</B>
  81
  82 <P>
  83 In order to show (manage) the canvas call the <I>show</I> member function:
  84
  85 <DL>
  86 <DD>virtual void show ( )</DD>
  87 </DL>
  88
  89 This member-function is responsible for cycling all of the installed documents
  90 and calling their respective <I>XsMDIWindow::_buildClientArea()</I>
  91 member-functions.  After each document has been created, <I>show</I> will then
  92 manage each document and, finally, itself.
  93
  94 <P>
  95 <B>Window Placement:</B>
  96
  97 <P>
  98 The current implementation of <I>XsMDICanvas</I> uses a very simple algorithm
  99 to place the documents on the canvas.  In order to implement a more specific
 100 placement algorithm, derive a class from <I>XsMDICanvas</I> and override
 101 the member-function:
 102
 103 <DL>
 104 <DD>virtual  void _placeWindow (XsMDIWindow *win)</DD>
 105 </DL>
 106
 107 <P>
 108 This member-function is called for each document in the canvas to compute
 109 the location of the document.  Please refer to the code (<I>XsMDICanvas.C</I>)
 110 for more details.
 111
 112 <P>
 113 <B>Canvas Behaviour:</B>
 114
 115 <P>
 116 The <I>XsMDICanvas</I> is implemented as an <I>XmScrolledWindow</I> with an
 117 <I>XmDrawingArea</I> work-window.  The instance name for the work-window
 118 is <I>canvas</I>.  Internal callbacks in the canvas class force the work-window
 119 to be at-least the size of the clip-window.  This prevents documents from
 120 being clipped as they are moved around.
 121
 122 <P>
 123 By default, the <I>XmDrawingArea</I> work-window has its <I>XmNresizePolicy</I>
 124 set to <I>XmRESIZE_GROW</I>.  This will allow the work-area to grow to
 125 whatever size necessary, but it will not automatically shrink as windows
 126 are manipulated.  If different behaviour is desired, the <I>XmNresizePolicy</I>
 127 resource on the work-area can be set to <I>XmRESIZE_ANY</I>.  This will
 128 force the work-window to recompute its size as windows are manipulated, and
 129 it will grow and shrink as necessary.  However, the <I>XsMDICanvas</I> will
 130 still force the work-area to be at-least the size of the clip-window.
 131
 132 <P>To change the default behaviour, add the following resource:
 133
 134 <DL>
 135 <DD>&ltXsMDICanvas name&gt*canvas.resizePolicy:   XmRESIZE_ANY</DD>
 136 </DL>
 137
 138 </BODY>
 139 </HTML>
 140