View source for Notebook Key Processing

Written by [[Roman Stangl]]

<h2>The problem</h2>

<p>The OS/2 PM notebook control has a limitation that causes inconsistent
usability compared to other PM controls, namely it does not pass on all
unprocessed messages to its owner.

</p><p>As a result the following consequences, which we want to avoid, exist:

</p><ul>

<li>Breaking this focus chain means, for example, that if the input focus
    is on a control of a notebook page, and one presses e.g. Alt+F and there
    exists a notebook tab having the letter F as the shortcut key, the key
    doesn't get passed on to the notebook, so that it can adjust itself to
    display the corresponding notebook page as the top page.

</li><li>Pressing the ESC key to cancel would dismiss the dialog that
    implements the notebook page, but not the window containing the notebook
    control.

</li><li>Pressing the Enter key does not dismiss the dialog window by selecting
    the default pushbutton (e.g. Save, Ok,...).

</li><li>Pressing accelerator keys does not trigger pushbuttons on your
    dialog's window.

</li></ul>

<h2>The window layout we assume</h2>

<p>A typical window containing a notebook is a dialog window (most likely
created with the dialog editor) that contains a <b>Notebook Control</b>
and <b>Pushbuttons</b> in its client area.  The notebook below should
demontrate this.

</p><p>By the way, the screen capture was taken from my <b>Program
Commander/2</b> (PC/2) program, which is available from <a href="http://www.geocities.com/SiliconValley/Pines/7885/">my homepage</a>,
and it's Freeware!

[[Image:Nbkey.gif|A typical dialog containing a notebook  control]] 

</p><p>This will probably not be new to you, however I would like to summarize
this from the point of the Z-Order and owner chain, as this is the basis
to understand how to enhance the processing.  The controls in the above
notebook are created in the following order:

</p><ol>

<p></p><li>The <b>Dialog Window</b> is the PM window that implements the whole
    dialog, which is created by the Dialog editor and processed by the OS/2 PM
    APIs <i>WinDlgBox()</i> or <i>WinLoadDlg(), WinProcessDlg()</i>.  If you
    for example press ESC, you want this <b>Dialog Window</b> to be dismissed.

<p></p></li><li>The client area of the <b>Dialog Window</b> consists of the
    <b>Notebook control</b> and the <b>Pushbuttons</b> like <u>S</u>ave,
    <u>C</u>ancel and <u>H</u>elp. The important thing to mention here is,
    that the <b>Notebook Control</b> and the <b>Pushbuttons</b> are child
    windows of the <b>Dialog Window</b>.

<p></p></li><li>The <b>Notebook Control</b> is a complex OS/2 PM control that
    consists of the <b>Notebook Tabs</b>, the <b>Notebook Page(s)</b> (and the
    Status line and Page buttons not shown here).

<p></p></li><li>The <b>Notebook Tabs</b> are drawn by the <b>Notebook Control</b>.
    However you determine the text drawn onto the individual tabs and there is
    nothing that prevents you from including shortcut keys, for example to
    specify <u>O</u>ptions for your options notebook page.

<p></p></li><li>Finally, the <b>Notebook Control</b> contains an area where the
    <b>Notebook page(s)</b> are displayed at.  <b>Notebook Pages</b> are also
    dialog windows usually created by the dialog editor. When adding to a
    notebook, the notebook implicitely performs the <i>WinLoadDlg()</i> to
    load the dialog from a resource.

    <p>The <b>Notebook Control</b> keeps track of all the pages you have
    inserted and displays the <b>Notebook Page</b> that corresponds to the
    currently selected <b>Notebook Tab</b> and hides the other pages.

    </p><p>The important thing to mention here is, that the <b>Notebook Pages</b>
    are child windows of the <b>Notebook Control</b>.

</p></li></ol>

<h2>Possible solution</h2>

<h3>Instance data structure</h3>

<p>In order to forward key events from the notebook control to its owner, we
have to modify the way the <b>Notebook Control</b> processes such events,
in case the notebook is not interested in that event.

</p><p>When working with data that is window dependent (instance data), the
proper way is to use the window words to save a pointer to your data.  The
QWL_USER window word is reserved for the user and would be a good starting
point.

</p><p>However, while implementing the advanced processing, it can be useful
to store the data in the heap, as it can be accessed by the debugger even
when not stepping through a window procedure.  In the following code
excerpt, the processing supports 3 different dialogs.

</p><pre><small>
  typedef struct _NOTEBOOKSUBCLASS    NOTEBOOKSUBCLASS;

  /* Structure to save which notebook was subclassed
     from which previous window procedure */
  struct  _NOTEBOOKSUBCLASS
  {
  HWND    hwndNotebook;    /* Notebook window handle */
  PFNWP   pfnwpNotebook;   /* Notebook control's window procedure
                              before subclassing */
  };

  /* Desktop dialog notebook subclassed */
  #define DD_SUBCLASSEDNOTEBOOK       0

  /* Program Installation dialog notebook subclassed */
  #define PI_SUBCLASSEDNOTEBOOK       1

  /* Control Configuration dialog notebook subclassed */
  #define CC_SUBCLASSEDNOTEBOOK       2

  /* As only one instance of the Desktop and Program Installation
     dialogs is allowed, its save to avoid more complicated
     per dialog instantiation, but use module class storage */
  #define NOTEBOOKSUBCLASSMAX         3

  NOTEBOOKSUBCLASS    DialogNotebookSubclass[NOTEBOOKSUBCLASSMAX];
</small></pre>

In this example our application consists of 3 different <b>Dialog
Windows</b> for which we want to enhance the message processing.

<h3>Modifying the notebook processing</h3>

<p>In order to forward key events from the notebook control to its owner, we
have to modify the way the <b>Notebook Control</b> processes such events,
in case the notebook is not interested in that event.

</p><p>In order to change the <b>Notebook Control's</b> default message
processing, we have to subclass the control by using the PM API
<i>WinSubclassWindow()</i>:

</p><pre><small>
    /* Subclass notebook's window procedure to add handling of
       notebook pages, notebook and outer dialog accelerator keys */
    DialogNotebookSubclass[DD_SUBCLASSEDNOTEBOOK].hwndNotebook=hwndNB;
    DialogNotebookSubclass[DD_SUBCLASSEDNOTEBOOK].pfnwpNotebook=
       WinSubclassWindow(hwndNB, SubclassedNotebookProcedure);
</small></pre>

Subclassing means, that we add a new window procedure to the existing
window procedure of the <b>Notebook Control</b> to be able to add
processing logic before the notebook's window procedure.  In your own
controls, you would add the processing somewhere in the big
<i>switch-Statement</i> of your window procedure, however as the notebook
(and all other controls shipped with OS/2) is implemented inside PM, you
can only get access to the control's window procedure by using
<i>WinSubclassWindow()</i>.

<p>Another thing to mention here is, that in our example all procedures
are coded only once, that is they run in the context of the window that is
currently processing the user input.  As a consequence special caution
needs to be taken not to share variables between different window
contexts.

</p><p>The subclassed window procedure of the <b>Notebook Control</b> is
especially interested in <i>WM_CHAR</i> messages, as the <i>WM_CHAR</i>
message reflects the keyboard input we want to change:

</p><p><a href="http://www.edm2.com/0508/nbkey1.c">Subclassed window procedure.</a>

</p><p>The first thing we do in the subclassed window procedure is look for
the control structure element that corresponds to the notebook control in
whose context we are currently running in.  As I said, the most elegant
way would be to use the notebook's window words, but the easier to debug
list approach is taken here.

</p><p>In detail, the following happens for a <i>WM_CHAR</i> message is routed
to the notebook:

</p><ol>

<p></p><li>As we have subclassed the notebook,
    <i>SubClassedNotebookProcedure()</i> will be called when the <b>Notebook
    control</b> has the input focus (e.g. when you click on one of the tabs),
    because it is now part of the notebook control's window procedure.

<p></p></li><li>A lookup is done to find out the instance data.

<p></p></li><li>The original notebook window procedure is called to see if the
    notebook does accept that key, which we know by the result returned. We
    are interested in the result, as we have to forward keys not accepted by
    the <b>Notebook Control</b> to the owning <b>Dialog Window</b>.

<p></p></li><li>If the key is the shortcut of a <b>Notebook Tab</b>, as for example
    the O for a <u>O</u>ptions tab, then the notebook will accept that key and
    switch to the <b>Notebook Page</b> corresponding to that tab.

    <p>If the key is not a shortcut accepted by the notebook, we will forward
    it to the <b>Dialog Window</b> (which is the owner of the <b>Notebook
    Control</b>), as for example the C key may be the accelerator key of a
    <u>C</u>ancel <b>Pushbutton</b>.

</p></li></ol>

<h3>Modifying the notebook pages' processing</h3>

<p>In the window procedure of the <b>Notebook Pages</b> we also have to catch
the key events, by looking for <i>WM_CHAR</i> messages.  As the dialog
that implements the notebook page is created by us, we also supply the
window procedure (or the dialog procedure to be exact), so we just can
easily add the processing as shown here:

</p><pre><small>
  case WM_CHAR:
  /*
   * Process the navigation keys on this page and forward all
   * unprocessed keys to the dialog where the notebook is part of.
   *
  \*
      ProcessPageKey(hwndDlg, WinQueryWindow(hwndNotebook,
                                             QW_OWNER), mp1, mp2);
      break;
</small></pre>

In order to allow window procedures of different notebook pages to share
the same implementation, all <i>WM_CHAR</i> messages are processed by
ProcessPageKey().

<p><b>Note:</b> If you have multiple notebook pages you can write window
procedure and share it for all notebook pages, just ensure that the
controls of the individual notebook pages contain different identifiers.

</p><p><a href="http://www.edm2.com/0508/nbkey2.c">ProcessPageKey</a>

</p><p>This function is somewhat more complex.  In order to make debugging
easier, <i>printf()</i> calls are added to generate debug information. You
can either redirect stdout to a file (e.g. by invoking myapp.exe with
"myapp &gt; debuginfo"), or you get the very useful IBM EWS-written
<b>PMPRINTF</b> package, which replaces the C-library <i>printf()</i>
function with one that writes into an OS/2 queue, and using the included
PM viewer you can display that queue in real-time.

</p><p>In detail, the following happens for a <i>WM_CHAR</i> message routed to
a notebook page's dialog procedure:

</p><ol>

<p></p><li>If the key event is a navigation key, that is the tab and cursor
    keys, we accept the processing of the <b>Notebook Page</b>'s window
    procedure.

<p></p></li><li>If the key event is not a navigation key, we ask the <b>Dialog
    Window</b> if the key makes sense there, for example the ALT+C key for a
    <u>C</u>ancel <b>Pushbutton</b>).

</li></ol>

<h3>Modifying the dialog window's processing</h3>

<p>The <b>Dialog Window</b> may process messages either generated while the
dialog had the input focus, or messages forwarded up from the owner chain,
that is message forwarded by the <b>Notebook Control</b> and by the
individual <b>Notebook Pages</b>.  In any case, we are interested in the
processing of WM_CHAR messages as shown below.

</p><p>Again, as the dialog that implements the dialog window is created by
us, we also supply the window procedure (or the dialog procedure to be
exact), so we just can easily add the <i>WM_CHAR</i> processing.

</p><pre><small>
  case WM_CHAR:

  /*
   * All window procedure implementing a noteboook page and the notebook
   * control itself, which is part of this window's client, forward
   * keystroke messages they don't have handled themselves here.
  \*
  {
      static ULONG    ulRecursion=FALSE;

      return(DispatchKeyToNotebook(&amp;ulRecursion, hwndDlg, hwndNB,
          DialogNotebookSubclass[DD_SUBCLASSEDNOTEBOOK].pfnwpNotebook, mp1, mp2));
  }
</small></pre>

To share code, again we call a function named <a href="http://www.edm2.com/0508/nbkey3.c">DispatchKeyToNotebook()</a>.  As a notebook page's window
procedure calls the dialog's window procedure by using <i>WinSendMsg()</i>
(as shown in <a href="http://www.edm2.com/0508/nbkey2.c">ProcessPageKey()</a>) and
<i>DispatchKeyToNotebook()</i> again calls the notebook page's window
procedure, we have to check for recursion.

<p>The reason why we may get into recursion is, that while processing a
key in the <b>Dialog Window</b>'s dialog procedure, we no longer know
where it was generated, that is in the dialog window itself, or sent from
one of the owned controls.  However, we want our logic to enhance the key
processing to work in all cases, so we have to take the recursion into
account.

</p><p><a href="http://www.edm2.com/0508/nbkey3.c">DispatchKeyToNotebook</a>

In detail, the following happens for a <i>WM_CHAR</i> message routed to
the dialog procedure:

</p><ol>

<p></p><li>We check if this key is the ESC or Enter key, as they are used to
    dismiss the dialog, causing the <b>Pushbuttons</b> <i>DID_CANCEL</i> for
    ESC and <i>DID_OK</i> for Enter to be selected.

    <p>One thing to note is that Enter (<i>VK_ENTER</i>) is not the same as
    Newline (<i>VK_NEWLINE</i>).  If Enter (that is the "Enter" key on the
    numeric keybad) is pressed, we want the dialog to be dismissed, but not in
    the case of Newline, because notebook pages may contain controls that
    allow you to input the "Enter" key (e.g. multiline entryfields), and your
    user for sure want to be able to input that key too.  On a Laptop, some
    key combinations may be required to select the Enter key instead of the
    Newline key (as Laptops usually have no numeric keybad).  You may try
    SHIFT+Enter, which works on IBM ThinkPads, or take a look into your User's
    Guide.

</p><p></p></li><li>To prevent recursion, one static variable per <b>Dialog Window</b>
    is used to track the recursion depth.

<p></p></li><li>After having protected us against recursion (and still running in
    the <b>Dialog window</b>'s dialog procedure), we check if the key event is
    a key press while the ALT key is still pressed (as accelerator keys
    usually are used in conjunction with the ALT key).

<p></p></li><li>If the key is pressed while the ALT key is still pressed, we check
    if the dialog procedure of the <b>Dialog Window</b> can accept that key,
    by calling the dialog's window procedure and checking the result returned.
    This would allow for example the ALT+C key for <u>C</u>ancel to be
    accepted.

<p></p></li><li>If the dialog window procedure does not accept that key, we query
    the window handle of the top <b>Notebook Page</b>, that is the one
    displayed in the <b>Notebook Control</b>.  If the notebook page could
    handle it we're done.

<p></p></li><li>If that <b>Notebook Page</b> can't accept that key, see if the
    <b>Notebook page</b> can accept that key as if no ALT key has been
    pressed.  We remove the ALT modifier, as if a notebook control has the
    input focus one can navigate between the notebook pages by pressing the
    accelerator key, for example O for <u>O</u>ptions without being required
    to hold the ALT key meanwhile.

<p></p></li><li>If the <b>Notebook Control</b> can accept that key, find out the
    <b>Notebook page</b> that has been put onto top and activate the control
    that had the input focus immediately before that notebook page was paged
    away.

</li></ol>

<h2>Credits</h2>

<p>The code shown here was greatly influenced by some discussions in the OS/2
development fora on the IBMPC conference disk.


[[Category:PM Articles]]