wxRuby Documentation Home

Wx::Notebook

This class represents a notebook control, which manages multiple windows with associated tabs.

To use the class, create a Notebook object and call add_page or insert_page, passing a window to be used as the page. Do not explicitly delete the window for a page that is currently managed by Notebook.

NotebookPage is a typedef for Window.

Derived from

Control

Window

EvtHandler

Object

Window styles

NB_TOP Place tabs on the top side.
NB_LEFT Place tabs on the left side.
NB_RIGHT Place tabs on the right side.
NB_BOTTOM Place tabs under instead of above the notebook pages.
NB_FIXEDWIDTH (Windows only) All tabs will have same width.
NB_MULTILINE (Windows only) There can be several rows of tabs.
NB_NOPAGETHEME (Windows only) Display a solid colour on notebook pages, and not a gradient, which can reduce performance.
NB_FLAT (Windows CE only) Show tabs in a flat style.

The styles NB_LEFT, RIGHT and BOTTOM are not supported under Microsoft Windows XP when using visual themes.

See also window styles overview.

noteevt.inc

Page backgrounds

On Windows XP, the default theme paints a gradient on the notebook’s pages. If you wish to suppress this theme, for aesthetic or performance reasons, there are three ways of doing it. You can use NB_NOPAGETHEME to disable themed drawing for a particular notebook, you can call SystemOptions::SetOption to disable it for the whole application, or you can disable it for individual pages by using SetBackgroundColour.

To disable themed pages globally:

SystemOptions::SetOption(T("msw.notebook.themed-background"), 0);

Set the value to 1 to enable it again.

To give a single page a solid background that more or less fits in with the overall theme, use:

Colour col = notebook->GetThemeBackgroundColour();
if (col.Ok())
{
    page->SetBackgroundColour(col);
}

On platforms other than Windows, or if the application is not using Windows themes, GetThemeBackgroundColour will return an uninitialised colour object, and the above code will therefore work on all platforms.

See also

BookCtrl, NotebookEvent, ImageList, notebook sample

Methods

Notebook.new

Notebook.new(Window parent,  Integer id, 
             Point pos = DEFAULT_POSITION, 
             Size size = DEFAULT_SIZE,  Integer style = 0, 
             String name = NotebookNameStr)

Constructs a notebook control.

Note that sometimes you can reduce flicker by passing the CLIP_CHILDREN window style.

Parameters

Destroys the Notebook object.

Notebook#add_page

Boolean add_page(NotebookPage page,  String text, 
                 Boolean select = false, 
                 Integer imageId = -1)

Adds a new page.

The call to this function may generate the page changing events.

Parameters

Return value

true if successful, false otherwise.

Remarks

Do not delete the page, it will be deleted by the notebook.

See also

Notebook#insert_page

Notebook#advance_selection

advance_selection(Boolean forward = true)

Cycles through the tabs.

The call to this function generates the page changing events.

Notebook#create

Boolean create(Window parent,  Integer id, 
               Point pos = DEFAULT_POSITION,  Size size,  Integer style = 0, 
               String name = NotebookNameStr)

Creates a notebook control. See Notebook.new for a description of the parameters.

Notebook#delete_all_pages

Boolean delete_all_pages()

Deletes all pages.

Notebook#delete_page

Boolean delete_page(Integer page)

Deletes the specified page, and the associated window.

The call to this function generates the page changing events.

Notebook#get_current_page

Window get_current_page()

Returns the currently selected notebook age or NULL.

Notebook#get_image_list

ImageList get_image_list()

Returns the associated image list.

See also

ImageList, Notebook#set_image_list

Notebook#get_page

NotebookPage get_page(Integer page)

Returns the window at the given page position.

Notebook#get_page_count

Integer get_page_count()

Returns the number of pages in the notebook control.

Notebook#get_page_image

Integer get_page_image(Integer nPage)

Returns the image index for the given page.

Notebook#get_page_text

String get_page_text(Integer nPage)

Returns the string for the given page.

Notebook#get_row_count

Integer get_row_count()

Returns the number of rows in the notebook control.

Notebook#get_selection

Integer get_selection()

Returns the currently selected page, or $-1$ if none was selected.

Note that this method may return either the previously or newly selected page when called from the EVT_NOTEBOOK_PAGE_CHANGED handler depending on the platform and so NotebookEvent#get_selection should be used instead in this case.

Notebook#get_theme_background_colour

Colour get_theme_background_colour()

If running under Windows and themes are enabled for the application, this function returns a suitable colour for painting the background of a notebook page, and can be passed to SetBackgroundColour. Otherwise, an uninitialised colour will be returned.

Notebook#hit_test

Integer hit_test(Point pt,  Integer flags = NULL)

Returns the index of the tab at the specified position or NOT_FOUND if none. If flags parameter is non NULL, the position of the point inside the tab is returned as well.

NB: * This method is currently only implemented under MSW and Univ.

Parameters

NB_HITTEST_NOWHERE There was no tab under this point.
NB_HITTEST_ONICON The point was over an icon (currently MSW only).
NB_HITTEST_ONLABEL The point was over a label (currently MSW only).
NB_HITTEST_ONITEM The point was over an item, but not on the label or icon.

Return value

Returns the zero-based tab index or NOT_FOUND if there is no tab is at the specified position.

Notebook#insert_page

Boolean *insert_page(Integer index,  NotebookPage page, 
                    String text, 
                    Boolean select = false, 
                    Integer imageId = -1)

Inserts a new page at the specified position.

Parameters

Return value

true if successful, false otherwise.

Remarks

Do not delete the page, it will be deleted by the notebook.

See also

Notebook#add_page

Notebook#on_sel_change

on_sel_change(NotebookEvent event)

An event handler function, called when the page selection is changed.

See also

NotebookEvent

Notebook#remove_page

Boolean remove_page(Integer page)

Deletes the specified page, without deleting the associated window.

Notebook#set_image_list

set_image_list(ImageList imageList)

Sets the image list which can be used to supply icons for each tab within the notebook.

Once an image list has been assigned to a Notebook, it “belongs” to the Notebook, and should not be set as the image list for another Notebook or other control.

Notebook#set_padding

set_padding(Size padding)

Sets the amount of space around each page’s icon and label, in pixels.

NB: The vertical padding cannot be changed in GTK.

Notebook#set_page_size

set_page_size(Size size)

Sets the width and height of the pages.

NB: This method is currently not implemented for GTK.

Notebook#set_page_image

Boolean set_page_image(Integer page,  Integer image)

Sets the image index for the given page. image is an index into the image list which was set with Notebook#set_image_list.

Notebook#set_page_text

Boolean set_page_text(Integer page,  String text)

Sets the text for the given page.

Notebook#set_selection

Integer set_selection(Integer page)

Sets the selection for the given page, returning the previous selection.

The call to this function generates the page changing events.

See also

Notebook#get_selection

[This page automatically generated from the Textile source at Thu May 01 00:50:42 +0100 2008]