Wx::Frame

From WxPerl wiki

Jump to: navigation, search

A frame is a top-level window whose size and position can (usually) be changed by the user. It usually has thick borders, a title bar, a menu bar, tool bar, and status bar, although these are optional elements. A frame is what users think of when they think of the term "window".

Generally, instead of using the Wx::Frame class directly, you will define a custom class that inherits from Wx::Frame -- or several such classes, one for each kind of top-level frame your application can have. These classes define the look of your application.

Contents

Example 

package MyFrame;
use Wx qw();
use base Wx::Frame;         # This class is a child of Wx::Frame.

# Provide our own constructor
sub new
{
    my $class = shift;

    # Invoke the base constructor to make the frame the way we want
    my $self = $class->SUPER::new(
        undef,         # No parent means "top-level window".
        -1,            # No need to assign a window ID
        "The Title",   # Window title
        [-1, -1],      # Let the system assign the window position
        [-1 ,-1],      # Use a default size
        # optionally specify a window style here
    );

    # Generally, you want to create a Panel to hold child controls:
    my $panel = Wx::Panel->new($self);

    # Add controls here
    my $text_control = Wx::StaticText->new(
        $panel,        # parent window
        -1,            # Let the system assign a window ID
        "Hello, World!",    # The literal text to display
        [10, 25],      # [x, y] coordinates of the control
    );

    # --- Add other controls as needed ---

    return $self;
}

Styles

Several window "styles" are available; they affect various aspects of the window's appearance and behavior. These can be combined with the Perl binary-or operator ( | ).

  • wxICONIZE
  • wxCAPTION
  • wxMINIMIZE
  • wxMINIMIZE_BOX
  • wxMAXIMIZE
  • wxMAXIMIZE_BOX
  • wxCLOSE_BOX
  • wxSTAY_ON_TOP
  • wxSYSTEM_MENU
  • wxRESIZE_BORDER
  • wxFRAME_TOOL_WINDOW
  • wxFRAME_NO_TASKBAR
  • wxFRAME_FLOAT_ON_PARENT
  • wxFRAME_EX_CONTEXTHELP
  • wxFRAME_SHAPED
  • wxFRAME_EX_METAL

These symbols are exported by the Wx module. See Window Styles for more information. The default is wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER | wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN.

Constructor

new 

$frame = Wx::Frame->new($parent, $id, $title, $pos, $size, $style, $name);

or (within a chid class): 

$self = $class->SUPER::new($parent, $id, $title, $pos, $size, $style, $name);

This is the constructor. Usually, you will be creating a child class, so you will be using the second form to invoke the base class constructor.

Parameters:

  • $parent -- The window parent. For a top-level window, pass undef. If you use a reference to an existing frame, then the fram you are creating wil always be displayed on top of the parent window (at least on Windows).
  • $id -- An integer specifying the window identifier. Usually you will specify -1 to let the system assign a window ID automatically.
  • $title -- The caption to be displayed on the frame's title bar.
  • $pos -- The window position, a reference to an array containing an x and a y coordinate. The special value [-1, -1] tells the system to choose the window's starting position.
  • $size -- The size of the window frame, a reference to an array containing a width and a height. The special value [-1, -1] tells the system to use a default size.
  • $style -- The Window Style to use (see above). Optional.
  • $name -- The name of the window. This parameter is used to associate a name with the window, which allows certain windowing systems to search for the window by name, and allows X resources values to be applied to the window by name.

Methods

Centre 

$frame->Centre();
$frame->Centre($direction);

Centers the frame on the display. $direction may be wxHORIZONTAL, wxVERTICAL, or wxBOTH. If it is omitted, it defaults to wxBOTH. These constants are exported by Wx.

Create 

$bool = $frame->Create(@options);

Used in something called "two-step frame construction". I have not been able to find details on what this is, or why it would be useful.

CreateStatusBar 

$bar = $frame->CreateStatusBar($number, $style, $id, $name);

Creates a status bar at the bottom of the frame. The status bar is always full-width (adjusted automatically when the frame is resized); its height and text size are chosen by the host windowing system.

Returns

A status bar of type Wx::StatusBar, or undef if it was not created successfully.

Options:

  • $number -- The number of fields to create; defaults to 1. This is used to create a multi-field status bar.
  • $style -- The style of the status bar. See Status Bar Styles.
  • $id -- The window identifier for the status bar. If -1, an identifier will be chosen by the system.
  • $name -- A string to identify the status bar.

CreateToolBar 

$bar = $frame->CreateToolBar($style, $id, $name);

Creates a toolbar at the top or left of the frame.

Returns

A status bar of type Wx::ToolBar (or a specialized class; see below), or undef if it was not created successfully.

Parameters:

  • $style -- The style of the toolbar. Allowed values include wxNO_BORDER and wxTB_HORIZONTAL (these constants are exported by Wx). See ToolBar Styles.
  • $id -- The window identifier for the status bar. If -1, an identifier will be chosen by the system.
  • $name -- A string to identify the status bar.

Remarks

By default, the toolbar returned is an instance of Wx::Toolbar, which is a platform-specific toolbar class, such as wxToolBar95. To create a toolbar of a different class, override the OnCreateToolbar method.

When a toolbar has been created with this function, or made known to the fram with the SetToolBar method, the frame will manage the toolbar position and adjust the return value from the Wx::Window::GetClientSize method, to reflect the available space for application windows.

GetClientAreaOrigin 

$point = $frame->GetClientAreaOrigin();

Returns the origin of the frame client area (in client coordinates). It may be different from (0, 0) if the frame has a toolbar. The returned value is a Wx::Point object.

GetMenuBar 

$menu = $frame->GetMenuBar();

Returns a reference to the menubar currently associated with the frame, or undef if the frame has no menubar.

See also: #CreateMenuBar, Wx::MenuBar

GetStatusBar 

$bar = $frame->GetStatusBar();

Returns a reference to the status bar currently associated with the frame, or undef if the frame has no statusbar.

See also: #CreateStatusBar, Wx::StatusBar

GetStatusBarPane 

$pane = $frame->GetStatusBarPane();

Returns the status bar pane used to display menu and toolbar help.

See also: #SetStatusBarPane

GetToolBar 

$bar = $frame->GetToolBar();

Returns a reference to the toolbar currently associated with the frame, or undef if the frame has no toolbar. The returned value is a Wx::ToolBar object.

See also: #CreateToolBar

OnCreateStatusBar 

sub OnCreateStatusBar
{
    my $self = shift;
    my ($num, $style, $id, $name) = @_;
...

This method is called when a status bar is requested by #CreateStatusBar. You only need to define this function if you wish to create a status bar other than the default kind of status bar.

The default implementation of this method returns an object that is an instance of Wx::StatusBar.

OnCreateToolBar 

sub OnCreateToolBar
{
    my $self = shift;
    my ($style, $id, $name) = @_;
...

This method is called when a tool bar is requested by #CreateToolBar. You only need to define this function if you wish to create a tool bar other than the default kind of tool bar.

The default implementation of this method returns an object that is an instance of Wx::ToolBar.

ProcessCommand 

$frame->ProcessCommand($id);

Simulates a menu command.

Parameters:

  • $id -- The window ID of a menu item.

SendSizeEvent 

$frame->SendSizeEvent();

This function sends a dummy size event to the frame forcing it to reevaluate its children positions. It is sometimes useful to call this function after adding or deleting a children after the frame creation or if a child size changes.

Note that if the frame is using either sizers or constraints for the children layout, it is enough to call Layout() directly and this function should not be used in this case.

ShowMenuBar 

$frame->ShowMenuBar($menu_bar);

Tell the frame to show the specified menu bar. $menu_bar is an object of type Wx::MenuBar.

If the frame is destroyed, the menu bar and its menus will be destroyed also, so do not delete the menu bar explicitly (except by resetting the frame's menu bar to another frame or NULL).

Under Windows, a size event is generated, so be sure to initialize data members properly before calling SetMenuBar.

Note that on some platforms, it is not possible to call this function twice for the same frame object.

SetStatusBar 

$frame->SetStatusBar($status_bar);

Associates a status bar with the frame.

Parameters:

SetStatusBarPane 

$frame->SetStatusBarPane($n);

Set the status bar pane used to display menu and toolbar help. Passing -1 for $n disables help display.

SetStatusText 

$frame->SetStatusText($text, $field_num);

Sets the text for the status bar, and redraws the status bar.

Parameters:

  • $text -- The text to set in the specified status bar field.
  • $field_num -- The number of the status bar field to set (fields are numbered starting at 0).

SetStatusWidths 

$frame->SetStatusWidths($width1, $width2, ...);

Sets the widths of the fields in the status bar. You should pass as many arguments as there are fields; each argument should be an integer. Passing a value of -1 in any position indicates that the corresponding field is variable-width. At least one value you pass must be -1.

SetToolBar 

$frame->SetToolBar($bar);

Associates a toolbar with the frame.

Parameters:

Retrieved from "http://wxperl.pvoice.org/w/index.php/Wx::Frame"
Personal tools
Google AdSense