hiro API

Contents

Copyable objects:

Static objects:

Shared objects:

Color

Color holds pixel values.

Color();
Color(int red, int green, int blue, int alpha = 255);

explicit operator bool() const;
operator==(const Color& source) const -> bool;
operator!=(const Color& source) const -> bool;

alpha() const -> uint8;
blue() const -> uint8;
green() const -> uint8;
red() const -> uint8;
reset() -> self;
setAlpha(int alpha) -> self;
setBlue(int blue) -> self;
setColor(Color color = {}) -> self;
setColor(int red, int green, int blue, int alpha = 255) -> self;
setGreen(int green) -> self;
setRed(int red) -> self;
value() const -> uint32;

value() const -> uint32;

Returns 32-bit pixel value in A8R8G8B8 format. Note that alpha resides in the top 8-bits, even though setColor() takes alpha as its final argument. setColor() was designed this way so that alpha could be a default parameter.

Notes

Some hiro functions that take Color arguments do not support the alpha component, and will treat the color as opaque. For those that do, the colors here are traditional, rather than pre-multiplied.

Gradient

Gradient holds multiple Color values.

Gradient();

explicit operator bool() const;
operator==(const Gradient& source) const -> bool;
operator!=(const Gradient& source) const -> bool;

setBilinear(Color topLeft, Color topRight, Color bottomLeft, Color bottomRight) -> self;
setHorizontal(Color left, Color right) -> self;
setVertical(Color top, Color bottom) -> self;

Notes

Currently, the internal state of Gradient cannot be read out.

Alignment
Alignment();
Alignment(double horizontal, double vertical = 0.5);

explicit operator bool() const;
operator==(const Alignment& source) const -> bool;
operator!=(const Alignment& source) const -> bool;

horizontal() const -> double;
reset() -> self;
setAlignment(double horizontal = -1.0, double vertical = 0.5) -> self;
setHorizontal(double horizontal) -> self;
setVertical(double vertical) -> self;
vertical() const -> double;

Notes

Valid ranges for alignment are normalized from 0.0 (top, left) to 1.0 (bottom, right.)

The default value for setAlignment()'s horizontal parameter is -1.0. This is a special value that's treated as "no alignment defined", for the purposes of operator bool() being able to detect this state, to instead inherit alignment from a parent object.

Cursor

Specifies the location and selection of a text cursor.

Cursor(int offset = 0, int length = 0);

explicit operator bool() const;
operator==(const Cursor& source) const -> bool;
operator!=(const Cursor& source) const -> bool;

length() const -> int;
offset() const -> int;
setCursor(int offset = 0, int length = 0) -> self;
setLength(int length = 0) -> self;
setOffset(int offset = 0) -> self;

length() const -> int;

Returns the amount of selected characters.

Note that when the value is positive, it means the cursor is at the start of the selection; and when it the value is negative, it means the cursor is at the end of the selection. A value of zero indicates that no text is currently selected.

offset() const -> int;

Returns the position of the cursor.

Position

Coordinates of an object relative to its parent (if any.)

Position();
Position(int x, int y);

explicit operator bool() const;
operator==(const Position& source) const -> bool;
operator!=(const Position& source) const -> bool;

reset() -> self;
setPosition(Position position = {}) -> self;
setPosition(int x, int y) -> self;
setX(int x) -> self;
setY(int y) -> self;
x() const -> int;
y() const -> int;
Size

Size of an object.

Size();
Size(int width, int height);

explicit operator bool() const;
operator==(const Size& source) const -> bool;
operator!=(const Size& source) const -> bool;

height() const -> int;
reset() -> self;
setHeight(int height) -> self;
setSize(Size source = {}) -> self;
setSize(int width, int height) -> self;
setWidth(int width) -> self;
width() const -> int;

static const int Maximum = ~0;  //~0 == -1
static const int Minimum =  0;

Notes

For layouts, the Minimum and Maximum values hold special meanings. Minimum will set the width to the smallest size a widget can be without cutting off content. Maximum will grow the widget to consume as much space as possible.

Geometry

A combination of Position and Size.

Geometry();
Geometry(Position position, Size size);
Geometry(int x, int y, int width, int height);

explicit operator bool() const;
operator==(const Geometry& source) const -> bool;
operator!=(const Geometry& source) const -> bool;

height() const -> int;
position() const -> Position;
reset() -> self;
setGeometry(Geometry geometry = {}) -> self;
setGeometry(Position position, Size size) -> self;
setGeometry(int x, int y, int width, int height) -> self;
setHeight(int height) -> self;
setPosition(Position position = {}) -> self;
setPosition(int x, int y) -> self;
setSize(Size size = {}) -> self;
setSize(int width, int height) -> self;
setWidth(int width) -> self;
setX(int x) -> self;
setY(int y) -> self;
size() const -> Size;
width() const -> int;
x() const -> int;
y() const -> int;
Font

A font description including sizing and styling information.

Font(string family = "", uint size = 0);

explicit operator bool() const;
operator==(const Font& source) const -> bool;
operator!=(const Font& source) const -> bool;

bold() const -> bool;
family() const -> string;
italic() const -> bool;
reset() -> self;
setBold(bool bold = true) -> self;
setFamily(string family = "") -> self;
setItalic(bool italic = true) -> self;
setSize(uint size = 0) -> self;
size() const -> uint;
size(string text) const -> Size;

static const string Sans;
static const string Serif;
static const string Mono;

family() const -> string;

Returns the name of the font. Note that an empty string defaults to Font::Sans.

size() const -> uint;

Returns the point size of the font. Note that a value of zero indicates the platform's default size (usually equivalent to 8.)

Notes

The Font::Sans, Font::Serif, Font::Mono constants should be used whenever possible. Each hiro back-end will choose the best font for the given platform. If it's not obvious, Sans is shorthand for sans-serif, and Mono is shorthand for monospace.

You can specify any font installed on the system, but it will likely render your application non-portable if you do.

Hotkey

Hotkey encodes a sequence of key presses. When appended to Keyboard, these can be invoked upon calling Keyboard::poll().

Hotkey();
Hotkey(string sequence);

explicit operator bool() const;
operator==(const Hotkey& source) const -> bool;
operator!=(const Hotkey& source) const -> bool;

doPress() const -> void;
doRelease() const -> void;
onPress(function<() -> void> callback = {}) -> self;
onRelease(function<() -> void> callback = {}) -> self;
reset() -> self;
sequence() const -> string;
setSequence(string sequence) -> self;

sequence() const -> string;

Returns the sequence of keys needed to trigger the hotkey. Values are separated by "+". For example, "Control+Shift+F".

Notes

The key values are physical keys, rather than mapped keys. So there is no distinction between say capital and lowercase letters.

Application
static doMain() -> void;
static font() -> Font;
static name() -> string;
static onMain(function<() -> void> callback = {}) -> void;
static run() -> void;
static pendingEvents() -> bool;
static processEvents() -> void;
static quit() -> void;
static setFont(Font font = {}) -> void;
static setName(string name = "") -> void;

struct Windows {
  static doModalChange(bool modal) -> void;
  static onModalChange(function<(bool) -> void> callback = {}) -> void;
};

struct Cocoa {
  static doAbout() -> void;
  static doActivate() -> void;
  static doPreferences() -> void;
  static doQuit() -> void;
  static onAbout(function<() -> void> callback = {}) -> void;
  static onActivate(function<() -> void> callback = {}) -> void;
  static onPreferences(function<() -> void> callback = {}) -> void;
  static onQuit(function<() -> void> callback = {}) -> void;
};

static doMain() -> void;

Upon calling run(), the application will remain in a message loop. In order to perform background processing, assign onMain, and said callback will be invoked whenever the message loop is idle. Be sure to call usleep() inside of onMain to avoid consuming 100% of a thread's CPU resources.

static font() -> Font;

Returns the default application font (if a specific font isn't assigned to an individual object nor its parent.)

static name() -> string;

Returns the name of the application.

This is primarily used to locate application icons on Xorg (Linux, BSD). hiro will scan for {name}.png in the usual application icon folders, and use said icon if it is found. As such, you will want to assign this value as soon as possible, and before any windows are created.

static pendingEvents() -> bool;

Returns true if there are pending window event messages to be processed.

static processEvents() -> void;

Process any and all pending window event messages.

Generally, this shouldn't need to be called. And intentionally doing so can reduce performance.

static quit() -> void;

Upon calling run(), the application will sit in a modal loop. Call quit() to terminate this loop. This will effectively return from run().

Note that run() should only be called once, and quit() should only be called inside of callbacks fired from run().

static Windows

Certaion operations in Windows will force a modal loop where doMain() cannot be called; such as entering menus. This callback will alert your application before this happens, so it can take necessary precautions. Most notably, streaming sound applications using DirectSound will want to clear their audio buffer here.

Desktop
static size() -> Size;
static workspace() -> Geometry;

static size() -> Size;

Returns the size of the entire desktop (all monitors.)

static workspace() -> Geometry;

Returns the non-reserved area of the entire desktop. This is the area of the desktop not obscured by fixed, non-overlappable toolbars, panels, docks, etc.

When placing a window at a specific geometry, it is best to ensure it is placed inside of the workspace. Note that the Window::setAlignment() function will honor the workspace borders for you.

Monitor
static count() -> uint;
static geometry(uint monitor) -> Geometry;
static primary() -> uint;

static count() -> uint;

Returns the number of monitors used for the desktop.

static geometry(uint monitor) -> Geometry;

Returns the position and size within the desktop of a given monitor.

static primary() -> uint;

Returns the monitor number which is set as the primary display. Note that Window::setFullScreen() will honor the primary monitor for you.

Keyboard
static append(Hotkey hotkey) -> void;
static hotkey(uint position) -> Hotkey;
static hotkeyCount() -> uint;
static hotkeys() -> vector<Hotkey>;
static poll() -> vector<bool>;
static pressed(string key) -> bool;
static released(string key) -> bool;
static remove(Hotkey hotkey) -> void;

static const vector<string> keys;

static poll() -> vector<bool>;

Returns a vector containing the states of every keyboard key. A value of true indicates said key is being pressed down.

Calling this function also results in polling all hotkeys appended to the keyboard. Upon a hotkey being pressed or released, its callback will be triggered from inside poll().

static const vector<string> keys;

Returns string names for all of the key states returned by poll().

Mouse
enum class Button : uint { Left, Middle, Right };

static position() -> Position;
static pressed(Button) -> bool;
static released(Button) -> bool;
BrowserWindow

Platform-native common dialog for file and directory selection.

directory() -> string;
open() -> string;
save() -> string;
setFilters(lstring filters = {"*"}) -> self;
setParent(Window parent) -> self;
setPath(string path = "") -> self;
setTitle(string title = "") -> self;

directory() -> string;

Invokes folder selection dialog, and returns the path or an empty string.

open() -> string;

Invokes open file dialog, and returns the path or an empty string.

save() -> string;

Invokes save file dialog, and returns the path or an empty string. The dialog will always present an overwrite confirmation prompt if saving to an existing file.

setParent(Window parent) -> self;

If set, dialog will be displayed centered within the parent window.

MessageWindow

Platform-native common dialog for message boxes.

enum class Buttons : uint { Ok, OkCancel, YesNo, YesNoCancel };
enum class Response : uint { Ok, Cancel, Yes, No };

error(Buttons = Buttons::Ok) -> Response;
information(Buttons = Buttons::Ok) -> Response;
question(Buttons = Buttons::YesNo) -> Response;
setParent(Window parent) -> self;
setText(string text = "") -> self;
setTitle(string title = "") -> self;
warning(Buttons = Buttons::Ok) -> Response;

setParent(Window parent) -> self;

If set, dialog will be displayed centered within the parent window.

Property
Property(string name, string value = "");
operator==(const Property& source) const -> bool;
operator< (const Property& source) const -> bool;

name() const -> string;
setValue(string value = "") -> self;
value() const -> string;

Notes

Every Object (or any children that inherit from it) internally have a red-black tree of properties. Unless otherwise documented, these are never used internally by hiro: they are for storing user-data.

The storage format of the data is a string. But note that nall::string is fully binary safe, so you can technically store just about any kind of data in a property.