PMGuide - Notebook Controls

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

A notebook control (WC_NOTEBOOK window class) is a visual component that organizes information on individual pages so that a user can find and display that information quickly and easily. This chapter explains how to use notebook controls in PM applications.

About Notebook Controls

This notebook control component simulates a real notebook but improves on it by overcoming a notebook's natural limitations. A user can select and display pages by using a pointing device or the keyboard.

The notebook can be customized to meet varying application requirements, while providing a user interface component that can be used easily to develop products that conform to the Common User Access (CUA) user interface guidelines. The application can specify different colors, sizes, and orientations for its notebooks and whether an old notebook or a new style notebook is desired, but the underlying function of the control remains the same.

Notebook Styles for an Old Notebook

This section describes the notebook style components associated with an old-style notebook:

• Page buttons
• Major and minor tabs
• Status line
• Binding
• Intersection of back pages
• Tab shapes

Page Buttons

In the bottom-right corner of the notebook are the page buttons. These buttons let you bring one page of the notebook into view at a time. They are a standard component that is automatically provided with every old notebook. However, the application can change the default width and height of the page buttons by using the BKM_SETDIMENSIONS message. The page buttons always are located in the corner where the recessed edges of the notebook intersect.

Selecting the forward page button (the arrow pointing to the right) causes the next page to be displayed and selecting the backward page button (the arrow pointing to the left) causes the previous page to be displayed. Prior to inserting pages in the notebook, the page buttons are displayed with unavailable-state emphasis; therefore, selecting either page button would not bring a page into view.

Major Tabs

Major and minor tabs are used to organize related pages into sections. Minor tabs define subsections within major tab sections. The content of each section has a common theme, which is represented to the user by a tabbed divider that is similar to a tabbed page in a notebook, an address book, or a large dictionary.

The BKS_MAJORTABRIGHT style bit specifies that major tabs are to be placed on the right side of the notebook. This is the default major tab placement when the back pages intersect at the bottom-right corner of the notebook. The binding is located on the left, because it is always located on the opposite side of the notebook from the major tabs.

The placement of the major tabs is limited to one of the two edges on which there are recessed pages. For example, if the application specifies the back pages intersection at the bottom-right corner (BKS_BACKPAGESBR, the default), the major tabs can be placed on either the bottom edge (BKS_MAJORTABBOTTOM) or the right edge (BKS_MAJORTABRIGHT) of the notebook. In this situation, if the application specifies that major tabs are to be placed on the left or top edges of the notebook, the notebook control places them on the right edge anyway—the default placement for back pages intersecting at the bottom-right corner.

When major tabs are defined at the creation of the notebook they are not displayed on screen. Major tab attributes only show at the time a page is inserted into the notebook. This is done by specifying the BKA_MAJOR attribute in the BKM_INSERTPAGE message.

Minor Tabs

Minor tabs are specified using the BKA_MINOR attribute. Minor tabs always are placed perpendicular to the major tabs, based on the intersection of the back pages and the major tab placement. Only one major or minor tab attribute can be specified for each notebook page. Minor tabs are displayed only if the associated major tab page is selected or if the notebook has no major tab pages.

The placement of the minor tabs depends entirely on the placement of the back pages and major tabs, respectively. The minor tabs always are located on the recessed page side that has no major tabs.

Status Line

To the left of the page buttons in the default old notebook style setting is the status line, which enables the application to provide information to the user about the page currently displayed. The notebook does not supply any default text for the status line.

The application is responsible for associating a text string with the status line of each page on which a text string is to be displayed. The status line can be used in addition to the major and minor tabs to provide the user with additional information on a particular page in the notebook. It is commonly used in large notebooks to assist the user in navigating, by indicating that this page is page 1 of n.

The status text is drawn left-justified by default, but it can be drawn centered or right-justified. The same status text justification applies to all pages in the notebook. This setting is specified by the BKS_STATUSTEXTLEFT style bit. The location of the back pages intersection and the major tabs has no effect on the specification of the status line position. This style bit can be set for the entire notebook.

Binding

The notebook control resembles a real notebook in its general appearance. The default binding is solid and is placed on the left side. This binding is used if the BKS_SOLIDBIND style bit is specified or if no style bit is specified.

Two styles are provided for the notebook binding: solid and spiral. The notebook is displayed with a solid binding by default, but the application can specify BKS_SPIRALBIND to display a spiral binding.

The placement of the binding depends entirely on the placement of the back pages and major tabs, respectively. The binding always is located on the opposite side of the notebook from the major tabs.

Intersection of Back Pages

The recessed edges that intersect near the page buttons are called the back pages. The default notebook's back pages intersect in the bottom-right corner, which means the recessed pages are on the bottom and right edges. This setting is specified by the BKS_BACKPAGESBR style bit. The back pages are important because their intersection determines where the major tabs can be placed, which in turn determines the placement of the binding and the minor tabs.

The following table describes the available notebook control styles for an old notebook:

Back Pages	Major Tabs	Minor Tabs	Binding
Bottom-right (default)	Bottom	Right	Top
Bottom-right (default)	Right (default)	Bottom	Left
Bottom-left	Bottom (default)	Left	Top
Bottom-left	Left	Bottom	Right
Top-right	Top (default)	Right	Bottom
Top-right	Right	Top	Left
Top-left	Top	Left	Bottom
Top-left	Left (default)	Top	Right

Tab Shapes and Contents

The default shape of the tabs used on notebook divider pages is square. This setting is specified by the BKS_SQUARETABS style bit. The shape of the tabs can be square, rounded, or polygonal. The tab text can be drawn left-justified, right-justified, or centered. Once set, these styles apply to the major and minor tabs for all pages in the notebook. The location of the back pages intersection and the major tabs has no effect on the specification of the tab-shape position. As with the page buttons, the application can change the default width and height of the major and minor tabs by using the BKM_SETDIMENSIONS message.

A notebook tab can contain text, a bitmap, or be owner-drawn. Text is associated with a tab page by using the BKM_SETTABTEXT message. Notebook tab text is centered by default or by specifying the BKS_TABTEXTCENTER style when creating the notebook window. A bitmap is placed on a tab by using the BKM_SETTABBITMAP message. Since the bitmap stretches to fill the rectangular area of the tab, no style bits are needed for bitmap positioning. If neither a BKM_SETTABTEXT nor a BKM_SETTABBITMAP message is used, the notebook owner is responsible for drawing the tab when a WM_DRAWITEM message is received for the tab.

Summary of Notebook Styles for Old Notebook

The old notebook control provides style bits so that your application can specify or change the default style settings. One style bit from each of the following groups can be specified. If you specify more than one style bit, you must use an OR operator (|) to combine them.

• Type of binding
  • BKS_SOLIDBIND Solid (default)
  • BKS_SPIRALBIND Spiral
• Intersection of back pages
  • BKS_BACKPAGESBR Bottom-right corner (default)
  • BKS_BACKPAGESBL Bottom-left corner
  • BKS_BACKPAGESTR Top-right corner
  • BKS_BACKPAGESTL Top-left corner
• Location of major tabs
  • BKS_MAJORTABRIGHT Right edge (default)
  • BKS_MAJORTABLEFT Left edge
  • BKS_MAJORTABTOP Top edge
  • BKS_MAJORTABBOTTOM Bottom edge
• Shape of tabs
  • BKS_SQUARETABS Square (default)
  • BKS_ROUNDEDTABS Rounded
  • BKS_POLYGONTABS Polygonal
• Alignment of text associated with tabs
  • BKS_TABTEXTCENTER Centered (default)
  • BKS_TABTEXTLEFT Left-justified
  • BKS_TABTEXTRIGHT Right-justified
• Alignment of status-line text
  • BKS_STATUSTEXTLEFT Left-justified (default)
  • BKS_STATUSTEXTRIGHT Right-justified
  • BKS_STATUSTEXTCENTER Centered
• Styles not applicable to an Old Notebook
  • BKS_TABBEDDIALOG Indicates a new-style notebook is desired.
  • BKS_BUTTONAREA Creates common button area for a new notebook. (This style uses the same area as BKS_POLYGONTABS, so it may generate unexpected results if used.)

Notebook Styles for a New Notebook

This section describes the notebook style components associated with a new-style notebook:

• Dog-eared tab
• Major tabs
• Scroll tabs
• Status line
• Minor tabs and the Page List
• Common button area

A new-style notebook will reformat itself if a new font is dropped on the notebook window.

Dog-Eared Tab

The page buttons in the old notebook control have been replaced by a dog-eared tab in the upper-right hand corner of the control. Selecting the area behind the dog-eared tab causes the next page to be displayed and selecting the dog-eared tab itself causes the previous page to be displayed. Plus and minus symbols emphasize the directions the user can travel in the notebook. A + symbol in the area behind the dog-eared tab indicates the user can page forward, and a - symbol in the dog-eared tab indicates the user can page backward. The symbol disappears when there are no more pages to turn in that direction.

Major Tabs

Major tabs are used to organize related pages in sections. Major tabs in a new notebook may appear along the bottom of the notebook by specifying the BKS_MAJORTABBOTTOM style, or they may appear along the top of the notebook by default or by explicitly specifying the BKS_MAJORTABTOP style. The application can control whether the tabs are ordered from left to right or right to left by using the appropriate style. Minor tabs are no longer displayed as tabs on the new notebook. Minor tabs are shown as part of the page list. The following table describes the available notebook control styles:

Style	Left to Right (default)	Right to Left
BKS_MAJORTABTOP (default)	BKS_BACKPAGESTR	BKS_BACKPAGESTL
BKS_MAJORTABBOTTOM	BKS_BACKPAGESBR	BKS_BACKPAGESBL

Status Line

To the left of the dog-eared tab is the status line, which enables the application to provide information to the user about the page being displayed. The notebook does not supply any default text for this line, thus the application is responsible for associating a text string with the status line on each page of the notebook.

The status line is always next to the dog-eared tab, thus the BKS_STATUSTEXTLEFT, BKS_STATUSTEXTRIGHT, and BKS_STATUSTEXTMIDDLE styles are ignored.

Left and Right Scroll Tabs

Left and right scroll tabs appear as necessary on either side of the major tabs. Click on the appropriate scroll tab until the tab you want scrolls into view.

Page List

The page list is a popup menu that lists all the pages in the notebook. To display the page list, position the pointer on a notebook tab or border and click mouse button 2. If a major tab in the page list has more than one page associated with it, its pages are placed in a submenu.

The text displayed in the page list for a given page is determined by the minor tab, major tab, and status text associated with the page. If a minor tab is associated with a page, its text is used. If only a major tab is associated with a page, the major tab text is used. If no tab is associated with the page, the status line text is used for the page list. If no status text is provided for the page, the page list entry is left blank.

Common Button Area

When the BKS_BUTTONAREA style is set, a common button area is created to contain a set of push buttons which is the same on each notebook page. These buttons are children of the notebook window. Buttons common to all pages in the notebook can be added, and specific buttons for a given notebook page may also be added as needed. The button area is placed opposite the major tabs of the notebook.

Common buttons behave exactly like ordinary push buttons except that they are positioned and sized automatically by the notebook control. Notification messages from the buttons are sent to the current notebook page. Buttons common to all notebook pages are handled by the BKM_SETNOTEBOOKBUTTONS message. Buttons specific to a notebook page can be created as children of that notebook page using the BS_NOTEBOOKBUTTON style.

If you create BS_NOTEBOOKBUTTON style buttons for a notebook page, they will override the common buttons created by BKM_SETNOTEBOOKBUTTONS. For instance, if you want to have buttons Help and Default available on all pages but one, use the BKM_SETNOTEBOOKBUTTONS message to create them, but create BS_NOTEBOOKBUTTON style buttons on the page requiring special buttons, and they will be the ones shown when that particular notebook page is displayed.

The states of the buttons created using BKM_SETNOTEBOOKBUTTONS are not changed when the notebook page turns.

Summary of Notebook Styles for New Notebook

The new notebook control provides style bits so that your application can specify or change the default style settings. One style bit from each of the following groups can be specified. If you specify more than one style bit, you must use an OR operator (|) to combine them.

• New Notebook
  • BKS_TABBEDDIALOG Indicates a new notebook control is desired. (The default is an old notebook.)
• Location of major tabs
  • BKS_MAJORTABTOP Top edge (default)
  • BKS_MAJORTABBOTTOM Bottom edge
• Ordering of major tabs
  • BKS_BACKPAGESTR Left-to-right when BKS_MAJORTABTOP (default)
  • BKS_BACKPAGESTL Right to left when BKS_MAJORTABTOP
  • BKS_BACKPAGESBR Left-to-right when BKS_MAJORTABBOTTOM (default)
  • BKS_BACKPAGESBL Right-to-left when BKS_MAJORTABBOTTOM
• Button Area
  • BKS_BUTTONAREA Creates space above or below the notebook page for a set of push buttons.
• Styles ignored by New Notebook
  • BKS_SOLIDBIND Solid binding
  • BKS_SPIRALBIND Spiral binding
  • BKS_TABTEXTCENTER Centered tab text
  • BKS_TABTEXTLEFT Left-justified tab text
  • BKS_TABTEXTRIGHT Right-justified tab text
  • BKS_STATUSTEXTLEFT Left-justified status text
  • BKS_STATUSTEXTRIGHT Right-justified status text
  • BKS_STATUSTEXTCENTER Centered status text
  • BKS_MAJORTABRIGHT Major tabs on right edge
  • BKS_MAJORTABLEFT Major tabs on left edge
  • BKS_SQUARETABS Square tabs
  • BKS_ROUNDEDTABS Rounded tabs
  • BKS_POLYGONTABS Polygonal tabs (Do not specify with BKS_TABBEDDIALOG because this style overlaps BKS_BUTTONAREA and you might get unexpected results.)

Using Notebook Controls

The following sections describe how to create pages, insert pages into, create and associate windows for, and delete pages from a notebook.

Notebook Creation

You create a notebook by using the WC_NOTEBOOK window class name in the ClassName parameter of WinCreateWindow. The following sample code shows the creation of the notebook. The style set in the ulNotebookStyles variable (the BKS_* values) specifies that the notebook is to be created with a solid binding and the back pages intersecting at the bottom-right corner, major tabs placed on the right edge, shape tab square, tab text centered, and status-line text left-justified. These are the default settings and are given here only to show how notebook styles are set.

HWND    hwndNotebook;            /* Notebook window handle            */
ULONG   ulNotebookStyles;        /* Notebook window styles            */
ULONG   x, y, cx, cy;            /* Coordinates                       */

/**********************************************************************/
/* Set the BKS_style flags to customize the notebook.                 */
/**********************************************************************/
ulNotebookStyles =
  BKS_SOLIDBIND     |          /* Use solid binding                   */
  BKS_BACKPAGESBR   |          /* Set back pages to intersect at the  */
                               /* bottom-right corner                 */
  BKS_MAJORTABRIGHT |          /* Position major tabs on right side   */
  BKS_SQUARETABS    |          /* Make tabs square                    */
  BKS_TABTEXTCENTER |          /* Center tab text                     */
  BKS_STATUSTEXTLEFT;          /* Left-justified status-line text     */

/**********************************************************************/
/* Create the notebook control window.                                */
/**********************************************************************/
hwndNotebook =
  WinCreateWindow(
    hwndParent,                /* Parent window handle                */
    WC_NOTEBOOK,               /* Notebook window class               */
    NULL,                      /* No window text                      */
    ulNotebookStyles,          /* Notebook window styles              */
    x, y, cx, cy,              /* Origin and size                     */
    hwndOwner,                 /* Owner window handle                 */
    HWND_TOP,                  /* Sibling window handle               */
    ID_BOOK,                   /* Notebook window ID                  */
    NULL,                      /* No control data                     */
    NULL);                     /* No presentation parameters          */

/**********************************************************************/
/* Make the notebook control visible.                                 */
/**********************************************************************/
WinShowWindow(
  hwndNotebook,                /* Notebook window handle              */
  TRUE);                       /* Make the window visible             */

Changing Notebook Styles

The following sample code fragments show how to set the notebook style to spiral binding, back pages intersecting at the bottom-left corner, major tabs placed on the bottom edge, tab shape rounded, tab text left-justified, and status-line text centered.

/**********************************************************************/
/* Query for the existing notebook window style settings.             */
/**********************************************************************/
ulNotebookStyles =
  WinQueryWindowULong(hwndNotebook,    /* Notebook window handle      */
                      QWL_STYLE);      /* Set notebook style          */

/**********************************************************************/
/* Reset notebook window style flags, leaving window flags unchanged. */
/**********************************************************************/
ulNotebookStyles &= 0xFFFF0000;

/**********************************************************************/
/* Setup the new notebook window style flags.                         */
/**********************************************************************/
ulNotebookStyles |=
  BKS_SPIRALBIND     |         /* Use spiral binding                  */
  BKS_BACKPAGESBL    |         /* Set back pages to intersect at the  */
                               /* bottom-left corner                  */
  BKS_MAJORTABBOTTOM |         /* Position major tabs on bottom edge  */
  BKS_ROUNDEDTABS    |         /* Make tabs rounded                   */
  BKS_TABTEXTLEFT    |         /* Left-justified tab text             */
  BKS_STATUSTEXTCENTER;        /* Center status-line text             */

/**********************************************************************/
/* Set the new notebook style.                                        */
/**********************************************************************/
WinSetWindowULong(
  hwndNotebook,                /* Notebook window handle              */
  QWL_STYLE,                   /* Window style                        */
  ulNotebookStyles);           /* Set notebook style                  */

/**********************************************************************/
/* Invalidate to force a repaint.                                     */
/**********************************************************************/
WinInvalidateRect(
  hwndNotebook,                /* Notebook window handle              */
  NULL,                        /* Invalidate entire window,           */
  TRUE);                       /* including children                  */

Inserting Notebook Pages

After a notebook is created, pages can be inserted into the notebook by using the BKM_INSERTPAGE message. BKM_INSERTPAGE provides several attributes that can affect the inserted pages. When inserting pages into either a new notebook or an existing one, consider carefully how the user expects those pages to be organized.

Major and Minor Tabs

The two attributes that have the most impact on how notebook pages are organized are BKA_MAJOR and BKA_MINOR, which specify major and minor tabs, respectively. Major tab pages define the beginning of major sections in the notebook, while minor tab pages define the beginning of subsections within a major section. Major sections should begin with a page that has a BKA_MAJOR attribute. Within major sections, information can be organized into minor sections, each of which should begin with a page that has a BKA_MINOR attribute.

For an existing notebook, the underlying hierarchy, if one exists, must be observed when inserting new pages, to provide efficient organization and navigation of the information in the notebook. For example, if the notebook has minor sections but no major sections, you could confuse the user if you inserted a page with a major tab attribute between related minor sections or at the end of the notebook.

If you insert pages without specifying tab attributes, those pages become part of the section in which they are inserted. For example, if page 7 of your notebook has a minor tab and you insert a new page 8 without specifying a tab attribute, page 8 becomes part of the section that begins with the minor tab on page 7.

Because tab pages are not mandatory, the application can create a notebook that contains no major or minor tab pages. That style would be similar to that of a composition notebook.

Another group of attributes that can affect the organization of pages being inserted into a notebook consists of BKA_FIRST, BKA_LAST, BKA_NEXT, and BKA_PREV. These attributes cause pages to be inserted at the end, at the beginning, after a specified page, and before a specified page of a notebook, respectively.

Status Line

Each page has an optional status line that can be used to display information for the user. To include this status line, the application must specify the BKA_STATUSTEXTON attribute when inserting the page. If the application inserts the page without specifying this attribute, the status line is not available for that page.

To display text on the status line of the specified page, the application must use the BKM_SETSTATUSLINETEXT message to associate a text string with the page. A separate message must be sent for each page that is to display status-line text. If the application does not send a BKM_SETSTATUSLINETEXT message for a page, no text is displayed in the status line of that page. The application can send this message to the notebook at any time to change the status-line text. The status line can be cleared by setting the text to NULL.

The following sample code shows how to insert a page into a notebook, where the inserted page has a major tab attribute, the status line is available, and the page is inserted after the last page in the notebook. This sample code also shows how to associate a text string with the status line of the inserted page.

HWND  hwndNotebook;            /* Notebook window handle               */
ULONG ulPageId;                /* Page identifier                      */

/***********************************************************************/
/* Insert a new page into a notebook.                                  */
/***********************************************************************/
ulPageId = (ULONG) WinSendMsg(
  hwndNotebook,                /* Notebook window handle               */
  BKM_INSERTPAGE,              /* Message for inserting a page         */
  (MPARAM)NULL,                /* NULL for page ID                     */
  MPFROM2SHORT(
    BKA_MAJOR |                /* Insert page with a major tab         */
                               /* attribute                            */
    BKA_STATUSTEXTON,          /* Make status-line text visible        */
    BKA_LAST));                /* Insert this page at end of notebook  */

/***********************************************************************/
/* Set the status-line text.                                           */
/***********************************************************************/
WinSendMsg(
  hwndNotebook,                /* Notebook window handle               */
  BKM_SETSTATUSLINETEXT,       /* Message for setting status-line      */
                               /* text                                 */
  (MPARAM)ulPageId,            /* ID of page to receive status-line    */
                               /* text                                 */
  MPFROMP("Page 1 of 2"));     /* Text string to put on status line    */

Setting and Querying Page Information

The information for a page in the notebook can be set and queried with BKM_SETPAGEINFO and BKM_QUERYPAGEINFO respectively. By using these messages, all the information associated with a page can be accessed at once. In addition, BKM_SETPAGEINFO can be used to delay the loading of a page until it is turned to, by setting the bLoadDlg field to FALSE. By doing this for all pages in a notebook, the notebook is created much more quickly.

Associating Application Page Windows with Notebook Pages

After a page is inserted into a notebook, you must facilitate the display of information for this page when it is brought to the top of the book. The notebook provides a top page area in which the application can display windows or dialogs for the topmost page. For each inserted page, the application must associate the handle of a window or dialog that is to be invalidated when the page is brought to the top of the book. The application can associate the same handle with different pages, if desired.

The application must send a BKM_SETPAGEWINDOWHWND message to the notebook in order to associate the application page window or dialog handle with the notebook page being inserted. Once done, the notebook invalidates this window or dialog whenever the notebook page is brought to the top of the book. If no application page window handle is specified for an inserted page, no invalidation can be done by the notebook for that page. However, the application receives a BKN_PAGESELECTED notification code when a new page is brought to the top of the notebook, at which time the application can invalidate the page.

The notebook also sends a BKN_PAGESELECTEDPENDING notification code to the application before the new page is selected. The application can use this message to prevent the page from being turned to. This is useful when the application wants to validate a page's contents.

The following sections describe how to associate either a window handle or a dialog handle with an inserted page.

Associating a Window with a Notebook Page

A calendar example is used to show how a page can be implemented as a window. A calendar is divided into four years (major tabs). Within each year are months (minor tabs) grouped into quarters. The top page has a window associated with it. The window paint processing displays the days for the currently selected month and year.

The sample code in the following figure shows how the window procedure for the calendar is registered with the application. Also, it shows how the window is created and associated with the notebook page. The example ends by showing the window procedure for the associated window.

/*********************************************************************/
/* Registration of window procedure for calendar.                    */
/*********************************************************************/
WinRegisterClass(hab,               /* Register a page window class  */
                 "Calendar Page",   /* Class name                    */
                 PageWndProc,       /* Window procedure              */
                 CS_SIZEREDRAW,     /* Class style                   */
                 0);                /* No extra bytes reserved       */

/*********************************************************************/
/* Create the window.                                                */
/*********************************************************************/
hwndPage = WinCreateWindow(hwndNotebook,       /* Parent             */
                           "Calendar Page",    /* Class              */
                           NULL,               /* Title text         */
                           0L,                 /* Style              */
                           0, 0, 0, 0,         /* Origin and size    */
                           hwndNotebook,       /* Owner              */
                           HWND_TOP,           /* Z-order            */
                           ID_WIN_CALENDAR_PAGE,   /* ID             */
                           NULL,               /* Control data       */
                           NULL);              /* Presparams         */

/*********************************************************************/
/* Associate window with the inserted notebook page.                 */
/*********************************************************************/
WinSendMsg(hwndBook,
           BKM_SETPAGEWINDOWHWND,
           MPFROMLONG(ulPageId),
           MPFROMHWND(hwndPage));

/*********************************************************************/
/* Window procedure.                                                 */
/*********************************************************************/
MRESULT EXPENTRY PageWndProc(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2)
{
  HPS hps;

  switch (msg)
  {
    /*******************************************************************/
    /* WM_CREATE is sent when the window is created.                   */
    /*******************************************************************/
    case WM_CREATE:
      /*****************************************************************/
      /* Place window initialization code here.                        */
      /*****************************************************************/
      break;

    case WM_PAINT:
      hps = WinBeginPaint(hwnd, NULL, NULL);
      /*****************************************************************/
      /* Draw the calendar for the selected year and month.            */
      /*****************************************************************/
      /* ... */
      WinEndPaint(hps);
      break;

    default:
      return (WinDefWindowProc(hwnd, msg, mp1, mp2));
      break;
  }

  return (FALSE);
}

Associating a Dialog with a Notebook Page

To understand the notebook implemented as a dialog, a Properties Notebook is used. The various objects whose properties can be changed or updated are displayed as major tabs. Included are sections that represent a folder, printer, and display (major tabs). The printer object is currently selected. Within the printer object, the user can choose to "View" or "Update" (minor tabs) the printer settings. The topmost page is a printer dialog from which the user can update the printer name, type, and device information.

The following sample code shows how the printer dialog is created and associated with a notebook page. The example ends by showing the dialog procedure for the associated dialog.

#define INCL_DOSRESOURCES

APIRET       dlgret;
HWND         hwndPage, hwndNotebook;
PDLGTEMPLATE pDlgt;
SEL          sel = NULL;

/**********************************************************************/
/* Allocate memory.                                                   */
/**********************************************************************/
DosAllocMem((PPVOID)&pDlgt,
            sizeof(DLGTEMPLATE),
            PAG_COMMIT |
            PAG_READ   |
            PAG_WRITE);

/**********************************************************************/
/* Retrieve the dialog resource.                                      */
/**********************************************************************/
dlgret = DosGetResource((HMODULE)0,       /* Resource                 */
                                          /* (Obtain from executable) */
                        RT_DIALOG,        /* Resource type            */
                        ID_DLG_PRINTDRV,  /* Resource ID              */
                        (PPVOID)&pDlgt);  /* Dialog template address  */

/**********************************************************************/
/* Create a dialog.                                                   */
/**********************************************************************/
hwndPage = WinCreateDlg(HWND_DESKTOP,     /* Parent window handle     */
                        hwndBook,         /* Owner window handle      */
                        fnwpPrint,        /* Dialog procedure         */
                                          /* address                  */
                        pDlgt,            /* Dialog data structure    */
                                          /* address                  */
                        NULL);            /* Application data         */

DosFreeMem(pDlgt);                        /* Free memory              */

/**********************************************************************/
/* Associate dialog with the inserted notebook page.                  */
/**********************************************************************/
WinSendMsg(hwndBook,
           BKM_SETPAGEWINDOWHWND,
           MPFROMLONG(ulPageId),
           MPFROMHWND(hwndPage));

/**********************************************************************/
/* Dialog procedure.                                                  */
/**********************************************************************/
MRESULT EXPENTRY fnwpPrint(HWND hwndDlg, ULONG msg, MPARAM mp1, MPARAM mp2)
{
  switch (msg)
  {
    case WM_INITDLG:
      /****************************************************************/
      /* Place dialog initialization code here.                       */
      /****************************************************************/
      break;

    case WM_COMMAND:
      return ((MRESULT) FALSE);
      break;

    default:
      return WinDefDlgProc(hwndDlg, msg, mp1, mp2);
  }
  return WinDefDlgProc(hwndDlg, msg, mp1, mp2);
}

Deleting Notebook Pages

The BKM_DELETEPAGE message is used to delete one or more pages from the notebook. The application can delete one page (BKA_SINGLE attribute), all pages within a major or minor tab section (BKA_TAB attribute), or all of the pages in the notebook (BKA_ALL attribute). The default, if no attributes are specified, is to delete no pages. The following sample code shows how the BKM_QUERYPAGEID message is used to get the ID of the top page and how the BKM_DELETEPAGE message is then used to delete that page:

```c /**********************************************************************/ /* Set the range of pages to be deleted. */ /**********************************************************************/

/* Set attribute to delete a single page. */ usDeleteFlag = BKA_SINGLE;

/**********************************************************************/ /* Get the ID of the notebook's top page. */ /**********************************************************************/ ulPageId = (ULONG) WinSendMsg(

 hwndNotebook,                /* Notebook window handle              */
 BKM_QUERYPAGEID,             /* Message to query a page ID          */
 NULL,                        /* NULL for page ID                    */
 (MPARAM)BKA_TOP);            /* Get ID of top page                  */

/**********************************************************************/ /* Delete the notebook's top page. */ /**********************************************************************/ WinSendMsg(

 hwndNotebook,                /* Notebook window handle              */
 BKM_DELETEPAGE,              /* Message to delete the page          */
 MPFROMLONG(ulPageId),        /* ID of page to be deleted            */
 (MPARAM)usDeleteFlag);       /* Range of pages to be deleted        */

```

Notebook Colors

The application can change the color of any part of the notebook. The colors of some parts can be changed by specifying presentation parameter attributes in WinSetPresParam. Other colors can be changed by specifying notebook attributes in the BKM_SETNOTEBOOKCOLORS message. The following sections define which parts of the notebook can have their colors changed by each of these two methods.

Changing Colors Using WinSetPresParam

WinSetPresParam is used to change the color of the notebook outline, window background, selection cursor, and status-line text. The following list shows the mapping between the various notebook parts and their associated presentation parameter attributes:

• Notebook outline: PP_BORDERCOLOR or PP_BORDERCOLORINDEX. This color is set initially to SYSCLR_WINDOWFRAME.
• Notebook window background: PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX. This color is set initially to SYSCLR_FIELDBACKGROUND.
• Selection cursor: PP_HILITEBACKGROUNDCOLOR or PP_HILITEBACKGROUNDCOLORINDEX. This color is set initially to SYSCLR_HILITEBACKGROUND.
• Status-line text: PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX. This color is initially set to SYSCLR_WINDOWTEXT.

If a presentation parameter attribute is set, all parts of the notebook that are mapped to this color are changed. The following sample code shows how to change the color of the notebook outline:

/* Set number of bytes to be passed in usColorIdx */
/* for color index table value                    */
usColorLen = 4;
/* Set color index table value to be assigned */
ulColorIdx = 3;

/**********************************************************************/
/* Set the notebook outline color.                                    */
/**********************************************************************/
WinSetPresParam(
  hwndNotebook,                /* Notebook window handle              */
  PP_BORDERCOLOR,              /* Border color attribute              */
  usColorLen,                  /* Number of bytes in color index      */
                               /* table value                         */
  &ulColorIdx);                /* Color index table value             */

Changing Colors Using BKM_SETNOTEBOOKCOLORS

The BKM_SETNOTEBOOKCOLORS message is used to change the color of the major tab background and text, the minor tab background and text, and the notebook page background. The following list shows the mapping between the various notebook parts and their associated notebook attributes:

• Major tab background: BKA_BACKGROUNDMAJORCOLOR or BKA_BACKGROUNDMAJORCOLORINDEX. This color is set initially to SYSCLR_PAGEBACKGROUND. The currently selected major tab has the same background color as the notebook page background.
• Major tab text: BKA_FOREGROUNDMAJORCOLOR or BKA_FOREGROUNDMAJORCOLORINDEX. This color is set initially to SYSCLR_WINDOWTEXT.
• Minor tab background: BKA_BACKGROUNDMINORCOLOR or BKA_BACKGROUNDMINORCOLORINDEX. This color is set initially to SYSCLR_PAGEBACKGROUND. The currently selected minor tab has the same background color as the notebook page background.
• Minor tab text: BKA_FOREGROUNDMINORCOLOR or BKA_FOREGROUNDMINORCOLORINDEX. This color is set initially to SYSCLR_WINDOWTEXT.
• Notebook page background: BKA_BACKGROUNDPAGECOLOR or BKA_BACKGROUNDPAGECOLORINDEX. This color is set initially to SYSCLR_PAGEBACKGROUND.

If a notebook attribute is set, all parts of the notebook that are mapped to this color are changed. The following sample code shows how to change the color of the major tab background:

/* Color index value     */
ulColorIdx    = SYSCLR_WINDOW;
/* Major tab background  */
ulColorRegion = BKA_BACKGROUNDMAJORCOLORINDEX;

WinSendMsg(hwndBook,
           BKM_SETNOTEBOOKCOLORS,
           MPFROMLONG(ulColorIdx),
           MPFROMLONG(ulColorRegion));

Graphical User Interface Support for Notebook Controls

The following section describes the support for graphical user interfaces (GUIs) provided by the notebook control. Except where noted, this support conforms to the guidelines in the SAA CUA Advanced Interface Design Reference.

The GUI support provided by the notebook control consists of the notebook navigation techniques.

Notebook Navigation Techniques

The notebook control supports the use of a pointing device and the keyboard for displaying notebook pages and tabs and for moving the selection cursor from the notebook tabs to the application window and the other way around.

Note: If more than one notebook window is open, displaying a page or tab in one notebook window has no effect on the pages or tabs displayed in any other notebook window.

Pointing Device Support

A user can use a pointing device to display notebook pages or tabs by selecting the notebook components described in the following list. The CUA guidelines define mouse button 1 (the select button) to be used for selecting these components. This definition also applies to the same button on any other pointing device a user might have.

• Selecting tabs using a pointing device

A tab can be selected to bring a page that has a major or minor tab attribute to the top of the notebook. The selection cursor, a dotted outline, is drawn inside the tab's border to indicate the selected tab. In addition, the selected tab is given the same background color as the notebook page area. The color of the other tabs is specified in the BKM_SETNOTEBOOKCOLORS message. This helps the user distinguish the selected tab from the other tabs if different colors are used.

Because all tabs are mutually exclusive, only one of them can be selected at a time. Therefore, the only type of selection supported by the notebook control is single selection. This selection type conforms to the guidelines in the SAA CUA Advanced Interface Design Reference.

If the user moves the pointing device to a place in the notebook page window that can accept a cursor, such as an entry field, check box, or radio button, and presses the select button, the selection cursor is removed from the tab it is on and is displayed in the notebook page window. The selection cursor never can be displayed both on a tab and in the notebook page window at the same time.

• Selecting page buttons using a pointing device

A forward or backward page button can be selected to display the next or previous page, respectively, one at a time. The arrow pointing to the right is the forward page button, and the arrow pointing to the left is the backward page button. When the selection of a page button brings a page that has a major or minor tab to the top of the notebook, the selection cursor is drawn inside that tab's border.

• Selecting tab scroll buttons using a pointing device

A user can decrease the size of a notebook window so that some of the available notebook tabs cannot be displayed. When this happens, the notebook control automatically draws tab scroll buttons at the corners of the notebook side or sides to notify the user that more tabs are available.

Tab scroll buttons have another purpose: to give the user the means to scroll into view, one at a time, the tabs that are not displayed. The user does this by selecting a forward or backward tab scroll button, which causes the next tab to scroll into view, but does not change the location of the selection cursor. Once the tab is in view, the user can display that tab's page by selecting the tab.

A maximum of four tab scroll buttons can be displayed: two for the major tab side and two for the minor tab side.

When the first tab in the notebook is displayed, the backward tab scroll button is deactivated. Unavailable-state emphasis is applied to it to show that no more tabs can be scrolled into view by using the backward tab scroll button. Unavailable-state emphasis is applied to the forward tab scroll button if the last tab in the notebook is displayed.

Keyboard Support

The users can utilize the keyboard to display and manipulate notebook pages and components.

Focus on Application Dialog or Window

If the application dialog page or window has the focus, the notebook handles the following keyboard interactions:

• Alt+PgDn or PgDn: Brings the next page to the top of the notebook. If the application uses the PgDn key, then it must be used in combination with the Alt key.
• Alt+PgUp or PgUp: Brings the previous page to the top of the notebook. If the application uses the PgUp key, then it must be used in combination with the Alt key.
• Alt+Up Arrow: Switch the focus to the notebook window.
• Tab: Move the cursor to the next control within the top page window or dialog. If the cursor is currently on the last control within the top page window or dialog when the Tab key is pressed, the cursor is moved to the notebook major tab, if it exists; else to the minor tab, if it exists; else to the right page button.
• Shift+Tab: Move the cursor to the previous control within the top page window or dialog. If the cursor is currently on the first control within the top page window or dialog when the Shift+Tab key is pressed, the cursor is moved to the previous control. If the previous control is the notebook, the cursor is moved to the right page button.

Focus on the Notebook Control

If the notebook control has the focus, it handles the following keyboard interactions:

• Alt+Down Arrow: Switch the focus to the application's primary window.
• Alt+PgDn or PgDn: Brings the next page to the top of the notebook.
• Alt+PgUp or PgUp: Brings the previous page to the top of the notebook.
• Left or Up Arrow:

• If the cursor is currently on a major tab, it is moved to the previous major tab. If the previous major tab is not visible, the tabs are scrolled to bring the previous major tab into view. If the first major tab is reached, scrolling ends.
• If the cursor is currently on a minor tab, it is moved to the previous minor tab. If the previous minor tab is not visible, the tabs are scrolled to bring the previous minor tab into view. If the first minor tab is reached, scrolling ends.
• If the cursor is currently on the right page button, the cursor moves to the left page button. If the cursor is currently on the left page button, no action is taken.
• Right or Down Arrow:
• If the cursor is currently on a major tab, it is moved to the next major tab. If the next major tab is not visible, the tabs are scrolled to bring the next major tab into view. If the last major tab is reached, scrolling ends.
• If the cursor is currently on a minor tab, it is moved to the next minor tab. If the next minor tab is not visible, the tabs are scrolled to bring the next minor tab into view. If the last minor tab is reached, scrolling ends.
• If the cursor is currently on the right page button, no action is taken. If the cursor is currently on the left page button, the cursor moves to the right page button.

• Tab: The cursor moves from the major tab, then to the minor tab, then to the right page button, and then to the last tab stop in the application dialog or window.
• Shift+Tab: The cursor moves from the page button, to the minor tab, to the major tab, and then to the first tab stop in the application dialog or window.
• Home: Brings the first page of the notebook to the top and sets the cursor on the associated tab.
• End: Brings the last page of the notebook to the top and sets the cursor on the associated tab.
• Enter or Spacebar:
  • If the cursor is on a major or minor tab, the associated page is brought to the top of the notebook, and the selected tab is given the same background color as the notebook page area. The other tabs have their color specified in the BKM_SETNOTEBOOKCOLORS message. This helps the user distinguish the selected tab from the other tabs if different colors are used.
  • If the cursor is currently on the right page button, the next page is brought to the top of the notebook. If the cursor is currently on the left page button, the previous page is brought to the top of the notebook.
• Mnemonics: Mnemonics are underlined characters in the text of a tab that cause the tab's page to be selected. Coding a tilde (~) before a text character in the BKM_SETTABTEXT message causes that character to be underlined and activates it as a mnemonic-selection character. A user performs mnemonic selection by pressing a character key that corresponds to an underlined character. When this happens, the tab that contains the underlined character is selected, and that tab's page is brought to the top of the notebook.

Note: Mnemonic selection is not case sensitive, so the user can type the underscored letter in either uppercase or lowercase.

Enhancing Notebook Control Performance and Effectiveness

This section provides the following information to enable you to fine-tune a notebook control:

• Dynamic resizing and scrolling
• Tab painting and positioning

Dynamic Resizing and Scrolling

The notebook control supports dynamic resizing by recalculating the size of the notebook's parts when either the user or the application changes the size of any of those parts. A BKN_NEWPAGESIZE notification code is sent from the notebook to the application whenever the notebook's size changes.

The notebook handles the sizing and positioning of each application page window if the BKA_AUTOPAGESIZE attribute is specified for the inserted notebook page. Otherwise, the application must handle this when it receives the BKN_NEWPAGESIZE notification code from the notebook.

If the size of the notebook window is decreased so that the page window is not large enough to display all the information the page contains, the information in the page window is clipped. If scroll bars are desired to enable the clipped information to be scrolled into view, they must be provided by the application. Tab scroll buttons are automatically displayed if the size of the notebook is decreased so that all the major or minor tabs cannot be displayed. For example, a notebook has major tabs on the right side, but the height of the notebook does not allow all the tabs to be displayed. In this case, tab scroll buttons are displayed on the upper- and lower-right corners of the notebook.

Tab Painting and Positioning

The tab pages provide a method for organizing the information in a notebook so that the user easily can see and navigate to that information. When a page is inserted with a major or minor tab attribute, the notebook displays a tab for that page, based on the orientation of the notebook. The contents of the tab can be painted either by the notebook control or the application.

If the notebook control is to paint the tabs, the application must associate a text string or bitmap with the page whose tab is to be drawn. This is done by sending the BKM_SETTABTEXT or BKM_SETTABBITMAP message to the notebook control for the specified page. If neither of these messages is sent for an inserted page with a major or minor tab attribute, the application must draw the contents of the tab, through ownerdraw. The application receives a WM_DRAWITEM message whenever a tab page that has no text or bitmap associated with it is to be drawn. The application can either draw the tab contents or return FALSE, in which case the notebook control fills the tab with the tab background color.

Positioning Tabs in Relation to the Top Tab:

There are seven page edges that define the back pages. The page attribute (BKA_MAJOR or BKA_MINOR) and the topmost page determine how the tabs are positioned. In most cases, the tabs must be drawn when their position changes. For example, this can happen when a page with a tab attribute is brought to the top of the notebook.

The new top major or minor tab will appear attached to the top page. The other tabs will appear as described in the following list. This information is provided to help you understand the relationship between the top tab and the other tabs so that you can organize the information you put into a notebook appropriately. The application has no control over tab positioning.

• When the top page is a major tab page:
  • Any major tabs prior to the top major tab are aligned on the last page of the notebook.
  • Any major tabs after the top major tab are incrementally cascaded from the topmost edge to the last page.
  • If the top major tab has minor tabs, no major tab is drawn on the page edge that immediately follows the top tab page. Instead, any major tabs that follow the top tab are incrementally cascaded, beginning on the second page, edge-down from the top tab. This is done to account for the minor tabs that are positioned between the top major tab and the major tab that follows it on the perpendicular notebook edge.
  • The minor tabs are all positioned on the third page edge from the top, thereby giving the appearance of being between the top major tab and the next major tab.

• When the top page is a minor tab page:
  • Any minor tabs prior to the top minor tab are positioned on the third page edge from the top of the notebook.
  • Any minor tabs after the top minor tab are incrementally cascaded up to the third page edge from the top.