Home > Releases > Simple2D 1.10 now available

Simple2D 1.10 now available


A new major release of Simple2D is now available (the download link can be found at the bottom of the page).

Version 1.10 introduces improved scene management, improved scene objects and user interface objects, object groups, customizable window resize and full-screen behaviour, more logical event dispatch, new time-based animation functions and a number of bug fixes.

System requirements

  • Windows 7 Service Pack 1 with Platform Update for Windows 7
  • Windows Server 2008 R2 Service Pack 1 with Platform Update for Windows 7
  • Windows 8

The installer will download and install Platform Update for Windows 7 for you if you don’t have it already.

Migrating from Simple2D 1.06 or later

Simply run the new installer. Your Simple2D installation will be upgraded automatically to the latest version. Please read the code migration guide below if you have existing applications built on Simple2D 1.07 or earlier.

Migrating from Simple2D 1.05 or earlier

  1. Uninstall Simple2D from Add/Remove Programs in Control Panel
  2. Run the new installer

Improvements and bug fixes

Animations:

  • The convenience function Get() is now available as a shortcut to GetAnimOffset(0.f).
  • The functions GetAnimOffsetTime(), GetAnimOffsetReversedTime(), GetAnimFixedTime(), GetAnimFixedReversedTime(), GetAnimPosTime(), GetAnimPosReversedTime() and SetPosTime() allow the animation position to be queried and set in units of milliseconds. These functions are identical to their 7 analogs without the Time suffix, except they take an integer in milliseconds offset from the animation start point instead of a percentage.  Note that GetAnimPosTime(int offset) returns the animation position in decimal percent offset from the absolute start of the animation, not from the start of the animation plus the current time position in it.

Images, bitmaps and sprites:

  • You can now provide an extra argument to the SpriteSheet (formerly SceneSpriteSheet) constructor to specify the number of frames in the animation. This will be calculated as the number of rows * number of columns in the sheet if not supplied, so is useful for when not all of the tiles in the final row are used.
  • You can now set the frame selector animation of a SpriteSheet to a single Animation (rather than an AnimationChain) and specify its cycle type with SpriteSheet::SetAnimatio(Animation &, Animation::CycleType).
  • Bug fix: Some rounding errors in SpriteSheet‘s drawing code could cause the selected tile co-ordinates within the sprite sheet to be off by one pixel (this needs further work)

Scene management:

  • Behavioural change: objects are now only updated and tested for pending removal in the per-frame update cycle if they are “on” (visible)
  • You can now set callback functions which will execute when a scene is turned on or off with Scene::SetOnActivateEventHandler(Simple2DVoidCallback) and Scene::SetOnDeactivateEventHandler(Simple2DVoidCallback). If you want to trigger the events manually, call Scene::OnActivate() or Scene::OnDeactivate(). Simple2D calls these automatically for you when the active scene changes.
  • You can now retrieve a pointer to the currently active scene by calling GetScene().
  • A default overlay scene is now provided which is always active and rendered after the currently active scene and the application’s DrawScene() override. This is useful if you want to display objects without creating your own scene, or for situations where there are certain objects that should always be displayed regardless of the active scene.
  • You can retrieve a reference to the overlay scene by calling GetOverlay().
  • You can retrieve a std::unique_ptr to the overlay scene via the Overlay property.
  • Changing or unsetting the active scene now unsets the focus object.
  • Bug fix: The pointers of objects marked for removal weren’t removed from the removal queue after they were removed from the scene. This caused many unnecessary list searches per frame, and if a released object was re-added, it would be immediately removed again.

Scene objects:

  • Object groups were added to allow a set of objects to be treated and animated as one. See the usage notes below.
  • Objects can now be added to scenes (and object groups) such that they are not destroyed when removed from the scene with the AddRef() methods. This means you can now add pointers and references to existing objects and manipulate them directly while they are part of the scene (or object group). They can also be removed and re-added as many times as desired. See the usage notes below.
  • Add() (and AddRef()) now accepts const objects without errors.
  • Add() is now overloaded to accept UserInterfaceItemGroup objects. Ownership of the objects in the container is transferred to the receiving scene or object group. The UserInterfaceItemGroup should be discarded after calling Add(). See the usage notes below.
  • The convenience function AddDrawing() allows you to add a custom drawing function to a scene or object group (the required CustomDraw object is automatically generated for you)
  • Remove() is now overloaded to accept a pointer to the object to remove.
  • Object lifetime control methods SetDeleteBehaviour() and GetDeleteBehaviour() were added. See the usage notes below.
  • Individual objects can now be made visible and hidden by calling On() or Off()
  • You can check if an object is currently visible by calling IsOn()
  • You can now obtain a reference to a bound variable in a scene object (for getting or setting) with the [] operator, eg. myObject[BindX] = 123;
  • The bindings BindBaseX and BindBaseY were added to support grouped objects (see regarding ObjectGroup below)
  • You can now call SceneObject::SetMasterAnimation() with no arguments to specify no master animation.
  • Custom-derived scene objects no longer require a forwarding constructor (no harm will be caused if existing forwarding constructors are left in-place)
  • All scene objects must now implement a virtual clone() method (NOTE: this is a breaking change to all applications which use custom scene objects derived from SceneObject. See the migration notes below)
  • Bug fix: calling ResetAnimations() did not reset any pending removal state, causing the object to be immediately removed from the scene if it had a master animation that had already completed at least once

User interface objects:

  • DrawingObjects are now InterfaceObjects and derive from SceneObject instead of being a self-contained hierarchy. Interface objects must now be added to a scene to be visible (NOTE: this is a breaking change to all applications which used DrawingObjects. See the migration notes below). InterfaceObjects now inherit all of the behaviour of a SceneObject which means they can have bound settings and animations, event triggers and so on. Some features from InterfaceObject were moved up into SceneObject such as the ability to turn objects on and off so that all scene objects can benefit from them (see above). Duplicate functionality between the two object hierarchies has been removed. The objects are no longer internally registered with Simple2D (the Simple2D::Register(DrawingObject &) and Simple2D::Unregister(DrawingObject &) methods are removed as is the drawing object unordered map and all the CheckDrawingObjects* event methods).
  • User interface elements are now switched on by default. See the migration notes below to retain the old behaviour.
  • The behaviour and intended use of the UserInterfaceItemGroup template class (including the pre-defined ButtonGroup class) has changed significantly. See the additional notes below (NOTE: this is a breaking change to all applications which used UserInterfaceItemGroup or ButtonGroup. See the migration notes below).
  • You can now set the text in a Label (formerly SceneText) with Label::SetText(string).
  • TextBox (formerly TextControl) can now have a “canvas” which defines the background onto which the editable text and caret is rendered. Previously an application had to render any control decoration manually. Use TextBox::SetCanvas() (6 arguments) to create a reounded rectangle background: specify the amount of x and y bleed (how many pixels padding outside/around the bounding box of the control to paint), the x and y corner radii (use zero for a non-rounded rectangle), the box outline brush and fill brush. Either of the latter can be set to NULL if you don’t want an outline or a fill.
  • The helper functions TextBox::TextAsChar()TextBox::TextAsInt()TextBox::TextAsFloat() and TextBox::TextAsDouble() convert the std::string contents of the editable text box to const char *intfloat, or double respectively to make it easier to retrieve numbers from editable text boxes.
  • The value of a Slider can now be set after it is created using Slider::SetValue(int) (the value is automatically clamped to within the slider’s allowed value range)
  • A new Checkbox control has been introduced, representing a 2-state tickable box with a caption on the right-hand side. See usage notes below.
  • All interface elements can now have focus (previously only text edit boxes could have the focus). An object receives focus when a left mouse-click is detected within its bounding box, and loses focus when a left-click is detected outside its bounding box, or another object gains the focus, or the application window loses focus.
  • You can now set/get the current focus object (the object which currently has the keyboard input focus) with:
    • void SetFocusObject(InterfaceObject &focus, bool set = true);
    • void SetFocusObject(InterfaceObject *focus, bool set = true);
    • InterfaceObject &GetFocusObject();If set is falsethe object loses focus if it already had it and the focus object is set to nothing, otherwise no action is taken. In other words, it de-focuses the object if it did have the focus.
    • Note: you should not generally call SetFocusObject() directly. Instead, call SetFocus(bool) on the InterfaceObject you wish to give or remove focus to/from. This will call SetFocusObject() for you as well as performing other tasks.
  • Bug fix: When focus changed from a TextBox (formerly TextControl) to another object, the caret was still displayed in the text box.
  • Bug fix: You could not give a TextBox focus when it had previously gained and lost the focus
  • Bug fix: Left-clicking outside a TextBox (or other user interface element) did not remove its focus
  • Bug fix: Clicking in a TextBox did not reset the tracking state of the Enter key to “not pressed”

Event handling:

  • Behavioural change: The order of dispatch for keyboard and mouse events has changed significantly. See the usage notes below.

Window handling:

  • The render target is now rendered in a frameless child window inside the main application window, to enable the resizing behaviours below. (NOTE: this is a breaking change to applications which use Windows controls in their application windows. See the migration notes below)
  • When resizable windows are enabled with Simple2D::SetResizeableWindow(true), you can configure the window resize behaviour with before calling Simple2D::Run() as follows:
    • Simple2D::SetResizeBehaviour(ResizeBehaviour) lets you specify one of four resizing behaviour options:
      • RB_Stretch – the render target is stretched to fill the window contents (this is the default behaviour from Simple2D 1.07 and earlier)
      • RB_Center – the render target is centered in the window surrounded by a black border (this is the default behaviour from Simple2D 1.10 onwards)
      • RB_Zoom – the render target is zoomed to fill as much of the window as possible while maintaining its aspect ratio correctly
      • RB_Resize – the render target is re-sized to fill the window, making the actual dimensions of the render target (in ResolutionX and ResolutionY) larger or smaller
    • Simple2D::SetMinimumWindowSize(int, int) allows you to specify the minimum dimensions that the window can be re-sized to
  • The following public properties are now available:
    • ResolutionX / ResolutionY – the resolution of the actual render target surface in pixels (no change)
    • RenderTargetX / RenderTargetY – the top-left co-ordinate of the render target relative to the main application window (these will be zero for RB_Stretch, RB_Resize and full-screen modes)
    • RenderTargetW / RenderTargetH – the scaled or stretched size of the render target as shown on the display (these will be the same as ResolutionX / ResolutionY for RB_Resize)
    • ClientW / ClientH – the size of the application client area (window) in pixels. This is essentially the window size (these will be the same as ResolutionX / ResolutionY for RB_Resize and full-screen mode regardless of the actual screen resolution)
    • MinWindowSizeX / MinWindowSizeY – the minimum dimensions that the application window can be shrunk to
  • Bug fix: Interface objects such as buttons and text boxes did not take into account a stretched render target. Mouse co-ordinates are now mapped correctly to objects in the render target regardless of which re-size behaviour is in use.

Rendering:

  • Applications can now run in full-screen. The behaviour can be configured before calling Simple2D::Run() as follows:
    • Simple2D::SetEnableFullScreen(bool) enables or disables the ability for the user to switch to and from full-screen with Alt+Enter. The default is enabled.
    • Simple2D::SetFullScreen(bool) determines whether the application should start in full-screen. The default is disabled.
    • Simple2D::SetEnableModeSwitch(bool) determines whether the application is allowed to change the screen mode when entering full-screen. The default is disabled.
  • HasFocus() will now also return true if the full-screen render target has the input focus, so you can use it without needing to know if the application is currently running windowed or full-screen
  • DXGISwapChain now points to the active swap chain, which is one of the two new public properties DXGISwapChainWindowed or DXGISwapChainFullScreen

Compilation behaviour:

  • All Visual Studio-specific and C++11-specific code has now been moved out of Simple2DLib.h and into Simple2D.cpp. This means you can now compile applications which use Simple2D without having Visual Studio or a C++11 compiler. To compile Simple2D itself, you need Visual Studio 2012 with the C++ Compiler November 2012 CTP.
  • SceneSceneObject and all objects derived from it (including user interface objects) are now located in the S2D::S2DScene namespace.

Other:

  • The new static member Simple2D::App provides a pointer to the main application class. This saves you from having to pass the application pointer to other class objects and hold copies of the pointer in those objects. All of the class constructors in Simple2D have been changed to no longer require the application pointer to be passed as the first argument (NOTE: this is a breaking change to applications which instantiate objects from the Simple2D hierarchy directly rather than using the Simple2D::Make*() factory functions. See the migration notes below)
  • The names of some types have been changed (NOTE: this is a breaking change to applications which use these types. See the migration notes below)
  • The new type Simple2DVoidCallback represents a function callback which takes no arguments and returns no value
  • Clean up: the unnecessary object LongLifeRenderingObjects and addLongLifeRenderingObject template have been removed

Installer:

  • The installer now checks for the presence of and downloads the final release of Platform Update for Windows 7 if needed (the previous version used the pre-release version of Platform Update for Windows 7).
  • You can now choose whether or not to install the code samples or just the libraries and source code.

Changes to example applications:

  • BoundingBoxDemo – shows how to use an InterfaceObject to implement a bounding box in which events can be received (updated from previous version which used a now-obsolete DrawingObject). Also demonstrates the RB_Zoom re-sizing mode and full-screen mode switching.
  • LinearMovementDemo – updated. The bouncing box effect demonstrated here requires the render target to be re-sized (RB_Resize) when the window is re-sized.
  • SceneGraphDemo – updated to show how custom scene objects should be derived from SceneObject, how to use and copy an ObjectGroup and how to use operator[] to change bound values.
  • SliderDemo – updated to use the overlay scene to display the slider control.
  • TextInputDemo – updated to show how to use the new SetCanvas() options to simplify the drawing code, and uses the overlay scene to display the editable text box. Also demonstrates the RB_Zoom re-sizing mode, full-screen mode switching and setting a minimum window size with SetMinimumWindowSize().
  • SimpleTetris 1.41 (separate download) has been updated to showcase many of the new features in Simple2D 1.10.

New example applications:

  • AsyncHTTPDemo – this example shows how to use a separate thread to do a long-running task (fetching a web page) while rendering continues. It demonstrates a re-usable notification bar class which uses a stack-allocated ObjectGroup to render an animated notification bar as different stages of the page fetch occur. The code uses boost::thread for multi-threading and WinINet to connect to the internet.

Full-screen Mode

Notes on mode switching

If the application starts in full-screen, the system will always switch screen mode to the mode which has the lowest resolution that is equal to or larger than the render target resolution. When transitioning from windowed mode to full-screen, a mode change will only occur if Simple2D::SetEnableModeSwitch(true) was called during application initialization, and this mode change will only change the color depth, not the screen resolution. This is due to the design of the underlying DXGI architecture. Simple2D will automatically stretch the render target to fit the screen resolution as if Simple2D::SetResizeBehaviour(RB_Stretch) was used when in full-screen. To avoid a mode switch when the application starts, or a stretched render target, set the render target resolution with Simple2D::SetResolution(GetSystemMetrics(SM_CXSCREEN), GetSystemMetrics(SM_CYSCREEN)) as a workaround until this problem is addressed in a later release. Note this only works if you are using the primary monitor for output.

Note on public properties values in full-screen mode

Please be aware that RenderTargetW and RenderTargetH are set to the dimensions of the mode being displayed on the monitor which contains the largest portion of the application window when you switch to full-screen mode. This will normally be correct but may under certain circumstances produce incorrect values for the render target width and height.

Scene Object Groups

The ObjectGroup object allows you to add a collection of SceneObjects in the same way as you would to a Scene, and manage them as one.

Both Scene and ObjectGroup now derive from SceneObjectManager which is an interface that manages a collection of SceneObjects, so all of the same object management functions in Scene, ie. Add(), AddRef() (see below), the new AddDrawing() and Remove() are available. ObjectGroup also derives from SceneObject so functions such as On() and Off() are also available.

Animating an object group

The top-left X and Y co-ordinates and the alpha channel of the group can be animated in Simple2D 1.10 (the latter is achieved by using Direct2D Layers functionality released in the Windows 8 version of Direct2D; it works on Windows 7 SP1 with Platform Update for Windows 7 installed, but not Windows Vista).

Note that ObjectGroups provide two sets of x/y bindings:

  • BindBaseX / BindBaseY – the top-left co-ordinate of the group relative to which all the objects in the group will be rendered
  • BindX / BindY – an offset to the top-left co-ordinate which is intended to be animated

If you want to animate the movement of the group relative to the base co-ordinates set when the group was initialized, use BindX and BindY with a base offset of zero. If you want to animate the movement of the group relative to the render target (or whole screen) in absolute pixel values from the top-left corner of the render target, use BindBaseX and BindBaseY. The two sets of values are added each frame to produce the final top-left co-ordinate where rendering will be oriented.

To animate the alpha blending amount (opacity), use BindAlpha.

Cloneability

ObjectGroups can be copy-constructed. When this happens, all of the objects in the original group are cloned, the clones are memory-managed by the new group and destroyed when the group is destroyed.

Events

Turning an ObjectGroup on or off does not call the on/off event handlers on all the child objects, only for the ObjectGroup itself. If you want to fire on/off events on child objects, call On() or Off() on the child objects directly.

The AsyncHTTPDemo example included in this release shows how to make use of ObjectGroup.

Scene Object Lifetime Management

Simple2D 1.07 provided these methods:

  • Scene::Add(&) – add an object to the scene from a reference. The object is cloned first and the clone is destroyed when removed from the scene. Intended use: auto-manage temporary SceneObjects created in the argument to Add(), or clone objects passed by value so that the original object is not incorrectly destroyed.
  • Scene::Add(*) – add an object to the scene from a pointer. The object is not cloned and the original object is destroyed when removed from the scene. Intended use: auto-manage previously created SceneObjects so that the creator does not have to remember to delete them.

Problems:

  1. You cannot create an object directly on the stack (without using new) and place it in the scene while still being able to access it. Either you pass by value in which case an inaccessible clone is made, or you pass by pointer in which case the object will be incorrectly destroyed leading to an application crash.
  2. Objects added via a pointer are not re-usable. If they are removed from the scene, they are destroyed and must be re-created from scratch if they are to be used again.

Simple2D 1.10 solves these problems by introducing an AddRef() method to Scene and ObjectGroup:

  • Scene::AddRef(&) and Scene::AddRef(*) – both add the supplied object to the scene (or object group) but do not destroy the object when it is removed from the scene. The object is merely released from the scene or group’s object list.

If the scene itself (or object group) is destroyed, only the objects added with Add() will be destroyed. Objects added with AddRef() will only be released.

The AsyncHTTPDemo example included in this release shows how to make use of these functions.

Changing an object’s lifetime

You can call SceneObject::SetDeleteBehaviour(SODB_Destroy) or SceneObject::SetDeleteBehaviour(SODB_Release) to configure what will happen to an object when it is removed from the scene or object group. NOTE: These functions are called automatically for you when you call Scene::Add() or Scene::AddRef() (or the object group equivalents), when an object is cloned or when a new object is created, and you should not use them directly unless you are sure you understand the implications.

You can check an object’s removal behaviour by calling SceneObject::GetDeleteBehaviour().

Changes to UserInterfaceItemGroup

These templates are a convenient way of organizing rows and columns of related user interface objects together without having to specify all of the parameters of each one by one.

Usage in previous versions of Simple2D:

  • Create UserInterfaceItemGroup concrete object (such as ButtonGroup)
  • Add desired interface elements
  • Turn the entire group on or off with On() and Off() when needed, draw entire group with Draw(). Each object in the group was registered with Simple2D as a DrawingObject.
  • The group object had a disableOnClick property which caused the entire group to be switched off when any item in the group is clicked (useful for eg. menus).
  • The object persisted over the lifetime of the application (or for as long as it is needed)

With the merging of the user interface object hierarchy with scenes and the additional features provided by scenes, this paradigm no longer makes sense.

UserInterfaceItemGroup is now intended to be used as a temporary object to collect together user interface elements as desired, then add them to a scene. Scene (and ObjectGroup) provide new overloads to allow a UserInterfaceItemGroup to be added directly to a scene. This causes each of the objects in the group to be added to the scene (or object group) and ownership of each object in the group is transferred to the scene. This means that the UserInterfaceItemGroup becomes useless once its contents have been added to a scene and should be destroyed.

Memory, rendering and event management that were previously handled by UserInterfaceItemGroup are now handled by the scene directly.

Added to UserInterfaceItemGroup: MoveItems() relinquishes ownership of all the objects in the group and returns them as a raw pointer to a boost::ptr_vector<InterfaceItem>, where InterfaceItem depends upon the template specialization instantiated (for example, ButtonGroup::MoveItems() returns a pointer to ptr_vector<Button>). MoveItems() is called internally by Scene (and ObjectGroup) to transfer ownership of the objects into the scene (or object group) when you add a UserInterfaceItemGroup to a scene (or object group).

Removed from UserInterfaceItemGroup: On(), Off(), Draw() and disableOnClick functionality.

Intended usage in Simple2D 1.10:

  • Create UserInterfaceItemGroup concrete object (such as ButtonGroup) by value (not with new)
  • Add desired interface elements
  • Add object to a Scene or ObjectGroup with Add(). Ownership of the interface elements is transferred to the scene (or object group).
  • Destroy the UserInterfaceItemGroup object by allowing it to fall out of scope
  • Set the active scene to the Scene object used above when you want the interface elements to be displayed

To implement the previous behaviours:

  • Turning all the interface elements on or off at once: Place them in their own Scene or ObjectGroup. You can change the active scene to display or hide all of the elements, or call On() or Off() on the ObjectGroup to turn them on or off without changing the active scene.
  • Hiding all the elements when one element is clicked: When an element is clicked, change the active scene to a different scene, or turn the ObjectGroup which owns the element off by calling Off().

The source code for SimpleTetris 1.4 and SimpleTetris 1.41 demonstrate these changes in a real-world application. The only difference between the two versions is that SimpleTetris 1.4 uses the old paradigm and SimpleTetris 1.41 uses the new one. The resulting code is cleaner and simpler.

Changes to Mouse and Keyboard Event Dispatch Order

Simple2D 1.07 and earlier

In Simple2D 1.07 and earlier, all events (character pressed, key down, key up, mouse move, mouse button down, mouse button up) were dispatched as follows:

  1. [Always] To the active scene if one exists
  2. [Always] To the main application class’s event handler overrides
  3. [If not processed by the main application class] To the list of registered user interface elements (DrawingObjects, now known as InterfaceObjects). Dispatch would occur in the order the objects were registered, and stop as soon as one had processed the event.

The scene dispatched the event as follows:

  1. If there is a user-defined callback function, dispatch the event to it. Continue if not processed.
  2. The event is not processed

The user interface elements dispatched the event as follows:

For all keyboard events:

  1. The event is not processed if the element is not visible. Otherwise continue.
  2. If there is a user-defined callback function, dispatch the event to it. Continue if not processed.
  3. Dispatch the event to the user interface element’s internal (virtual) event handler

For mouse buttons:

  1. The event is not processed if the element is not visible. Otherwise continue.
  2. The event is not processed if the mouse cursor is not in the element’s bounding box. Otherwise continue.
  3. If there is a user-defined callback function, dispatch the event to it. Continue if not processed.
  4. Dispatch the event to the user interface element’s internal (virtual) event handler

For mouse movement:

  1. The event is not processed if the element is not visible. Otherwise continue.
  2. If there is a user-defined callback function, dispatch the event to it. Continue if not processed.
  3. If the mouse has just entered the element’s bounding box, dispatch to the user-defined hover event handler if it is set, but don’t set the event as processed
  4. If the mouse has just left the element’s bounding box, dispatch to the user-defined unhover event handler if it is set, but don’t set the event as processed
  5. The event is not processed if the mouse cursor is not in the element’s bounding box. Otherwise continue.
  6. Dispatch the event to the user interface element’s internal (virtual) event handler
Simple2D 1.10

Event dispatch is now performed as follows:

For all keyboard events:

  1. [Always] To the object with focus if set
  2. [If not processed yet] To the active scene if one exists
  3. [If not processed yet] To the overlay scene
  4. [If not processed yet] To the main application class’s event handler overrides

For all mouse events:

  1. [Always] To the active scene if one exists
  2. [If not processed yet] To the overlay scene
  3. [If not processed yet] To the main application class’s event handler overrides

In other words, the focus object, active scene, overlay scene and application class event handlers are checked in sequence and the chain of checks is stopped as soon as the event is processed. Only keyboard events are sent directly to the focus object, not mouse events.

The focus object is an InterfaceObject and event dispatch to it is processed in the same way as for user interface elements in Simple2D 1.07 except for some additional processing code to deal with focus switching.

The active scene and overlay scene dispatch the event as follows:

For keyboard events:

  1. If there is a user-defined callback function, dispatch the event to it. Continue if not processed.
  2. The event is not processed

(the same as in Simple2D 1.07)

For mouse events:

  1. If there is a user-defined callback function, dispatch the event to it. Continue if not processed.
  2. Iterate over each object in the scene. If it is an InterfaceObject (or derived class), dispatch the event to it in the same way as for the focus object and user interface elements in Simple2D 1.07. This allows objects in a scene to gain focus by clicking on them, and to respond to hover events. Stop as soon as the event is processed, otherwise continue.
  3. The event is not processed

In this way, all user interface elements in both the active scene and overlay scene can receive events if they have not been processed by the focus object (where applicable), and if neither scene processes the event, it is finally sent to the application class’s event handlers.

CheckBox Control

The constructor takes 10 arguments of which the first 9 are required. They are:

  • int x, int y – top-left co-ordinate of the check box
  • int size – width and height of the check box in pixels
  • bool state – initial state (ticked or unticked)
  • std::string text – the caption to display to the right-hand side of the box
  • TextFormat format – the font etc. to use when rendering the text
  • GenericBrush *bb – the brush to use when rendering the check box outline
  • GenericBrush *tb – the brush to use when rendering the tick mark
  • GenericBrush *xb – the brush to use when rendering the caption text
  • boost::function<void (CheckBox &)> changeFunc [optional] – the function to call when the checkbox state changes

You can set the state after creating the object with SetChecked(bool), and read the state with bool IsChecked().

As with other interface objects, the CheckBox must be added to a Scene before it will be rendered.

Code Migration from Simple2D 1.07 and earlier

Type name changes: Some type names have changed. Here is a complete list:

1.07                1.10
=============================================
DrawingObject    -> InterfaceObject
SceneRectangle   -> Rectangle
SceneText        -> Label
SceneImage       -> Sprite
SceneSpriteSheet -> SpriteSheet
SceneCustomraw   -> CustomDraw
TextControl      -> TextBox

Constructor changes: The introduction of the static member Simple2D::App (see above) eliminates the need for pointers to Simple2D to be passed to other objects. All of the code in the Simple2D library has been re-factored to remove these constructor parameters. Existing code must be modified to remove the Simple2D pointer argument from calls to class constructors in the library before it will compile.

Backwards compatibility for type name changes and constructors: To retain partial compatibility for applications built on Simple2D 1.07 or below, link against Simple2Dd_compat107.lib (debug builds) or Simple2D_compat107.lib (release builds) and define SIMPLE2D_COMPAT_107 before you include Simple2D.h. This will enable the following compatibility features:

  • All type names changed in Simple2D 1.10 will have typedefs to alias the types to their Simple2D 1.07-equivalent names
  • Constructors which take a pointer to Simple2D in the following classes will still be available (the pointer parameter will be ignored and Simple2D::App will be used instead): RenderingObject, RenderingObjectNonShareable, RenderingObjectShareable, ImageObject, GenericBrush, PaintbrushObject, GradientObject, ImageBrushObject, Geometry, Rectangle (formerly SceneRectangle), Label (formerly SceneText), Sprite (formerly SceneImage), SpriteSheet (formerly SceneSpriteSheet), CustomDraw (formerly SceneCustomDraw), InterfaceObject (formerly DrawingObject), TextBox (formerly TextControl), Button, Slider. Notes: SceneObject will work with or without a Simple2D pointer argument regardless of the compatibility flag. The new class Checkbox does not have a constructor taking a pointer to Simple2D.

Resize behaviour: The default resize behaviour is now to centre the render target in the window. If you want the old stretch behaviour, call SetResizeBehaviour(RB_Stretch) before you call Run() on your application class (note that resizing the window at all is still disabled by default as in previous versions, so this only matters if your window is resizable).

Full-screen behaviour: Switching to full-screen with Alt+Enter is now enabled by default. If you want the old behaviour where full-screen is disabled, call SetEnableFullScreen(false) before you call Run() on your application class.

Application window Z-ordering behaviour: if you use Windows controls inside your application window, the new version of Simple2D which renders the render target to a frameless child window inside the application window may make controls you create unintentionally hidden. To prevent this, called the Win32 API function BringWindowToTop(hwnd) immediately after you create a rebar, toolbar, tab control or other child window of the main application window (handle obtained by calling Simple2D::GetWindow()). This will prevent the item from being occluded by the render target.

UserInterfaceItemGroup (including ButtonGroup) lifetime behaviour: This is a breaking change. You must update your code to use these objects as temporaries (see section above).

Interface object derivation from scene objects: This is a breaking change. You must update your code to add interface objects (objects derived from InterfaceObject, formerly DrawingObject) to a Scene or they will not be rendered. If you don’t want to manage your own scene, you can use the overlay scene provided in Simple2D 1.10 and above – use the Overlay property to access it (see above).

Interface object default state: Interface objects are now on (visible) by default. You no longer need to call On() on the object after creating it to make it display. If you want the object to be off by default, call Off() after you create the object to prevent it from being rendered, or don’t add it to a Scene immediately.

Scene Object namespace: Scene, SceneObject and all of its derived classes are now stored in the S2D::S2DScene namespace. This should have no impact on your code but the use of Rectangle may conflict with Rectangle defined in the Win32 API (wingdi.h). Use S2D::Rectangle to mitigate this problem.

Custom scene object cloning: This is a breaking change. When you derive an object from SceneObject, you must now provide a clone() function as follows:

class MyCustomObject : public SceneObject
{
protected:
  void doDraw() { ... }

public:
  virtual MyCustomObject *clone() const override {
    return new MyCustomObject(*this);
  }
};

This should be sufficient for most objects. If your derived class contains resources that should not be shallow copied, be sure to define a copy constructor and/or a move constructor.

Download

Download link (always download the latest version)

Please be aware that Simple2D is very much a work in progress, and that changes from version to version can break older code, although I try to maintain backwards compatibility as much as possible. The code is currently undergoing significant re-factoring with each new version.

I hope you find Simple2D useful!

For setup and installation instructions, follow the Simple2D Installation Tutorial.

Previous version release notes (1.07)

Advertisements
  1. No comments yet.
  1. August 29, 2013 at 05:50
  2. November 9, 2013 at 10:44
  3. March 28, 2014 at 13:11

Share your thoughts! Note: to post source code, enclose it in [code lang=...] [/code] tags. Valid values for 'lang' are cpp, csharp, xml, javascript, php etc. To post compiler errors or other text that is best read monospaced, use 'text' as the value for lang.

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: