API Changes

Here, you can find the API changes from the version 1.0. In addition, some hints are provided to help you update your code.



  • The class is added to the API.
  • The handle() method is now public as it should have been.


  • Add postpone_stop() and posptponed_quit() methods to handle event propagation.


  • New utility class to handle images tied to a palette group id.


  • Add an optional device argument to the constructor.


  • Add orient() getter and setter to handle the orientation: either vertical or horizontal.
  • Add scroll_beginning/end() methods.


  • Add drag_enable_distance() setter and getter to configure the distance to travel to enable drag mode.


  • Add translate() and rotate() methods to abstract Cairo translation and rotation.


  • Add unary 'operator-'.


  • Add rbegin(), rend(), crbegin(), and crend() iterators.


  • Add init_sliders() method.
  • Rename resize_slider() into resize_sliders();


  • Add format_label() method to handle the formatting of the value.
  • Add handle_image() setter and getter, and the reset_handle_method() to manage an optional image to draw for the handle.
  • Fix the prototype of the to_offset() method. The 'value' parameter should be 'T' rather than 'int'.


  • Add the Switch class to factorize code from CheckBox and RadioBox which now inherits from it.


  • Add an optional step parameter to the constructor and stepping() getter and setter. Step describes the difference between two consecutive values of the range.
  • Add the set_value() method to factorize code.


  • children() returns a reference rather than a value.
  • Add init() method to factorize code.
  • Add components() getters.
  • Add update_subordinates_ranges() method to factorize code.
  • Add the range_from_widget() method to return the proper subordinate range, either children or components depending on the type of the subordinate given as argument.
  • Constify local_to_display() and display_to_local() methods.
  • Add the point_from_subordinate() virtual method to return the widget point coordinates, but from the point of view of one of its subordinates.
  • Add the hit() method to test whether a DisplayPoint lays within a widget box.
  • Add dragged() setter and getter for the current widget which is being dragged.
  • Add group() method to retrieve the palette group id depending on the widget state.
  • Add background() setter and getter, and the reset_background() method to handle the image background per palette group.
  • The has_screen() method is now public.



  • Add style property to define the direction of the progress bar: left to right, right to left, bottom to top, or top to bottom.


  • Add enumarate_pcm_device() method to get a list of device names available.
  • Add media() method to set another file to play.
  • Add stop() method.



  • add demangle() function to the API.

Filesystem (C++ stdlib)

  • move to c++17 std::filesystem
    - #include <experimental/filesystem>
    - namespace fs = std::experimental::filesystem;
    + #include <filesystem>
    + namespace fs = std::filesystem;


  • remove the font_size() method as it mostly duplicates the text_size() method.


  • Remove add_node() and previous_node() methods.
  • Add begin_child() and end_child() methods.
  • Remove the level parameter of the add() method.


  • Remove justify parameter from prepare_text().
  • Remove justify and orient parameters from compute_layout().
  • Transform several static functions to instance methods: context(), tokenize(), compute_layout(), consolidate(), clear_selection(), set_selection(), get_line(), longest_prefix(), longest_suffix(), tag_default_aligned_line(), tag_left_aligned_line(), tag_right_aligned_line(), tag_line(), tag_text(), tag_line_selection(), tag_text_selection(), prepare_text(), get_cursor_rect(), draw_text().
  • Add horizontal_scrollable and vertical_scrollable flags to TextFlag and some methods to handle it: text_area(), init_sliders(), resize_sliders(), update_hslider(), update_vslider(), update_sliders(), draw_sliders(), damage_component(), damage_hslider(), damage_vslider(), move_hslider(), move_vslider(), move_sliders().
  • Add point2pos() method.
  • Add beginning_of_line() and end_of_line() methods.
  • Add up() and down() methods to handle UP and DOWN keys.


  • Children handling has been moved from Frame to Widget. It should be transparent for users. The main change is the set_parent() method that takes a Widget* parameter instead of a Frame* parameter. Now, Widget can be used to create widgets composed of several components. Prefer inheriting from Widget if users must not be able to use add or remove.



  • Switch to C++17


  • Add zorder setter to change the rank of a child.


  • Add operator== and operator!=.


  • Add zorder setter to change the rank.


  • Transform the WidgetFlag enum into a WidgetFlag class plus few other related classes: HorizontalBitField, VerticalBitField, ExpandBitField, HVBitField, HExpandBitField, VExpendBitField.
  • Override operators| to allow only valid combinations of WidgetFlag and related classes listed above.



  • Add a setter for the focus.


  • Make the handle_key() method virtual.



  • quit() method accepts an optional parameter corresponding to the exit value.


  • Add bank setter and getter.
  • Add xlabel, ylbabel and title setters.
  • Introduce ChartItemArray to replace DataArray and StringDataArray which were specific to each ChartBase subclass.
    - PieChart::StringDataArray data;
    - data.push_back(make_pair(25, "truck"));
    + egt::ChartItemArray data;
    + data.add(25, "truck");


  • Add show_label setter and getter.
  • Add checkbox_align setter and getter to set the alignement of the checkbox relative to the text.


  • Add another add_item() method that do not delegate the ownership of the StringItem to the ComboBox.


  • Add global_font setter and getter, and reset_global_font() method to manage a global font. So if a theme is used only to handle a palette and a font, prefer using the global font.


  • Add gride_size setter and getter.


  • Add uri() and reset_uri() methods to set/unset the image URI.
  • load() method takes an additional optional parameter to indicate if the scale can be approximated to increase iamge cache hit efficiency.


  • Add uri setter and getter.
  • Add reset_uri() method.
  • Add hscale, vscale and scale setters and getters.


  • Add another add_item() method that do not delegate the ownership of the StringItem to the ListBox.


  • Add global_palette setter and getter, and reset_global_palette() method to manage a global palette. So if a theme is used only to handle a palette and a font, prefer using the global palette.
  • Add empty() method to check if a palette is empty or not.


  • Add show_label setter and getter.
  • Add radiobox_align setter and getter to set the alignement of the radiobox relative to the text.


  • Add hoffset and voffset getters.
  • Add hpolicy and vpolicy getters and setters.


  • Add live_update getter.


  • Add text_flags setter.


  • Add name setter and getter as themes can be identified with their name.
  • Remove constructor dedicated to de-serialization and the serialization method. As a theme is more than a palette and a font, it can draw in a different way widgets, it can't be serialized entirely. So remove this feature.


  • Add has_font() method to check if the widget has a custom font.
  • Add reset_font() method to unset the widget's custom font.
  • Add has_palette() method to check if the widget has a custom palette.
  • Add palette getter to retrieve which palette is used by the widget.
  • Add reset_palette() method to unset the widget's custom font.
  • Remove theme getter and reset_theme() method. Local theme are no longer supported at the widget level. There is only one theme which is the global theme. If a local theme was used to set a palette and/or a font, prefer using the local palette/font. If it was used to draw the widget in a different way, prefer having a subclass of this widget where you override the draw method.
  • deseriliaze() method is no longer virtual as it's only called from constructors.


  • Add format_hint() setter and getter.
  • Add window_hint() setter and getter.



  • Add removeLast() method to remove the last sub animation from the sequence.
  • Add removeAt() method to remove the sub animation at the given position from the sequence.


  • Add default_size() setter and getter.


  • Add keep_image_ratio() setter and getter.


  • Add min_size_hint() getter.


  • Add selection_forward() and selection_backward() method to extend the selection.



  • Rename min and max to start and end. The constraint to get max > min is removed.


  • The constraint to get start > end is removed.
  • The origin_opposite flag is removed. As end can be greater than start, swap end and start instead of setting the origin_opposite flag.


  • The constraint to get start > end is removed.


  • Add keep_image_ratio() setter and getter. The keep image ratio state is set to true by default. When enabled, the image ratio is kept during the image auto scale operation.


  • Add keep_image_ratio() setter and getter. The keep image ratio state is set to true by default. When enabled, the image ratio is kept during the image auto scale operation.



The changes about ComboBox are about providing a common interface with ListBox.

  • Rename remove() to remove_item().
  • Uses StringItem as item type instead of string.
    - combo->add_item("Item1");
    + combo->add_item(std::make_shared<egt::StringItem>("Item1"))
    auto s = combo->item_at(i);
    - if (s == "ok")
    + if (s->text() == "ok")
  • Add show() and hide() member functions.


  • Restrict items to StringItem instead of Widgets.


  • Add n_col() and n_row() member functions to get the number of columns and rows.
  • Add add() member functions taking a GridPoint as parameter instead of column and row. Prefer these new member functions to the older ones.
    - grid.add(button, 2, 1);
    + grid.add(button, egt::StaticGrid::GridPoint(2, 1));
  • Layout changes: the border of the widget is no longer used to space out cells. Remove the border parameter from the constructor and add horizontal/vertical_space getters and setters.
    - auto grid = make_shared<StaticGrid>(StaticGrid::GridSize(2, 2), 1);
    + auto grid = make_shared<StaticGrid>(StaticGrid::GridSize(2, 2));
    + instance->horizontal_space(1);
    + instance->vertical_space(1);


  • Add auto_scale_image() setter and getter. The auto scale image state is set to true by default. When enabled, the image will be automatically scaled down to fit the box attributed by the align algorithm.