byuu's homepage

phoenix::Window

Represents a top-level window. Note that unlike with most toolkit APIs, phoenix treats Window and Widget as separate concepts. One does not inherit from the other, nor are they considered equals. A Widget is something that goes on a Window.

Also note that by frame geometry, I refer to the window manager's border, the menu bar, and the status bar. The reason I choose to also include the menu bar and status bar is because their heights are not under the control of the user. And further, some platforms may choose to place these elements outside of the window entirely, such as the OS X menu bar.

struct Window : Object {
  static Window None;

  function<void ()> onClose;
  function<void (Key)> onKeyPress;
  function<void (Key)> onKeyRelease;
  function<void ()> onMove;
  function<void ()> onSize;

  void append(Object&... objects);
  Color backgroundColor();
  Geometry frameGeometry();
  Geometry frameMargin();
  bool focused();
  bool fullScreen();
  Geometry geometry();
  void ignore();
  void remove(Object&... objects);
  void setBackgroundColor(const Color &color);
  void setFrameGeometry(const Geometry &geometry);
  void setFocused();
  void setFullScreen(bool fullScreen = true);
  void setGeometry(const Geometry &geometry);
  void setMenuFont(const string &font);
  void setMenuVisible(bool visible = true);
  void setResizable(bool resizable = true);
  void setStatusFont(const string &font);
  void setStatusText(const string &text);
  void setStatusVisible(bool visible = true);
  void setTitle(const string &text);
  void setVisible(bool visible = true);
  void setWidgetFont(const string &font);
  string statusText();
  void synchronize();
  bool visible();
};

static Window Window::None;

This is used solely to pass to OS functions that take an optional Window argument. It is meant as the reference-based alternative to passing around null pointers. Never use this object directly, or bad things will happen.

function<void ()> Window::onClose;

Called when the user closes a window. Note that the window will be hidden, but not destroyed. You can later call setVisible() to re-display the window.

function<void (Key)> Window::onKeyPress;

Sends a message for key presses that are not grabbed by controls on the window.

For instance, a TextEdit control would capture all key presses. A window with only a Canvas control would not capture any key presses.

function<void (Key)> Window::onKeyRelease;

Sends a message for key releases that are not grabbed by controls on the window.

function<void ()> Window::onMove;

Called when the user moves a window.

function<void ()> Window::onSize;

Called when the user resizes a window.

void Window::append(Object&... objects);

Layout&

Attaches a layout to a window. You are free to attach as many layouts as you like. Each layout will use the full window client area geometry. In general, it is not that useful to attach more than one layout; but it can make certain tasks easier, such as implementing stacked panels. You can also easily hide and show entire layouts at once.

Menu&

Attaches a menu group to the window's menu bar.

Widget&

Reparents a Widget onto this window. This function should only be used by classes that inherit from Layout. Bad things may happen if you try and use this anywhere else.

Color Window::backgroundColor();

Returns the current window background color. This can be called prior to calling setBackgroundColor() to get the default window color.

Geometry Window::frameGeometry();

Returns the geometry of the window, including the border, menu and status bars. If the menu or status are currently not visible, then they are not included in this geometry.

Geometry Window::frameMargin();

Returns margin information about the frame geometry. x, y represent the number of pixels from the top-left of the window until we reach the client area; and width, height represent the total width and height of the window border, menu and status bar.

You can determine the bottom-right widths by subtracting width, height from x, y.

bool Window::focused();

Returns true if the window has top-level focus. Use this when writing your own input polling routine to ignore keypresses when the window does not have focus.

bool Window::fullScreen();

Returns true if the window is currently in fullscreen mode.

Geometry Window::geometry();

The geometry of the window's client area. Note that x, y are relative to the desktop screen itself, and not relative to the window.

void Window::ignore();

Call this function from inside of callbacks to cancel their actions.

Presently, this function only has an effect inside of Window::onClose. When called, the window close action will be ignored.

Example:

window.onClose = [&] {
  if(MessageWindow::question(window, "Are you sure you want to quit?") == Response::No) {
    window.ignore();  //do not close window
  }
};

void Window::remove(Object&... objects);

Layout&

Removes the specified menu from the main menubar.

Menu&

Removes the specified layout, and all of its children layouts and widgets from the window.

Widget&

This is an internal function that only subclassed layouts should use. If you want to remove a widget from a window, remove it from the layout that contains it, by using Layout::remove(widget);

void Window::setBackgroundColor(const Color &color);

Sets the window background color. There is really only one time when you should ever consider using this, and that is when you are also using a centered viewport to display video output. In this instance, it would be preferrable to make the window background color black.

Label, CheckBox and RadioBox will be transparent to this color, so overriding this may result in invisible text, based on the user's color settings.

void Window::setFrameGeometry(const Geometry &geometry);

Used to set the total window size, including the frame. Use this when you want to place windows along specific edges of the screen.

void Window::setFocused();

Make a window the top-level window on the desktop.

void Window::setFullScreen(bool fullScreen = true);

Hides the window border, but not the menu and status bars, and stretches a window to fill the entire desktop. Use this to implement pseudo-fullscreen support in your application.

Upon reverting back to non-fullscreen mode, window geometry will be restored to what it was prior to entering fullscreen mode. Do not use the set*Geometry() functions while in fullscreen mode.

void Window::setGeometry(const Geometry &geometry);

Set the size and placement of the window client area. Be careful about setting the client placement to 0,0. Because of the window decoration, this will end up putting part of the window border offscreen.

void Window::setMenuFont(const string &font);

If the platform supports it, this will set the font of all menu items currently attached to the menu. Call this after all menus have been attached to the window.

void Window::setMenuVisible(bool visible = true);

Set visibility of the menu bar. Will resize window so as not to affect client geometry size.

void Window::setResizable(bool resizable = true);

Default is true, use this to prevent the user from resizing a window. Useful for FixedLayout.

void Window::setStatusFont(const string &font);

Set the font for status bar text.

void Window::setStatusText(const string &text);

Set the text to be display in the status bar.

void Window::setStatusVisible(bool visible = true);

Set visibility of the status bar. Will resize window so as not to affect client geometry size.

void Window::setTitle(const string &text);

Sets the title of the window.

void Window::setVisible(bool visible = true);

Sets the visibility of the window. New windows default to hidden, so that you can set up their widgets and menus prior to presenting them.

void Window::setWidgetFont(const string &font);

This will apply the font to all currently-attached Widget items that do not already have a custom font applied to them. Call this after appending all of your layouts to the window.

string Window::statusText();

Returns the current text being displayed in the status bar.

void Window::synchronize();

This is an internal function that only subclasses of Layout should use. It forces all appended layouts to update their geometry.

bool Window::visible();

Returns true if the window is currently visible.