TheBigUndo v1.1.0

TheBigUndo is a module that allows RealStudio developers to add undo/redo

functionality to their projects with little effort yet can be fully customized to provide

undos for difficult situations.

To Add TheBigUndo to a project, just drag the module and the CustomUndo Interface

to the project pane and add TheBigUndo.init to the app's open event. This will

provide basic undo functions to most controls.

Undos are created via an automatic check loop by default, but can also be manually

triggered. Undo check timing can be adjusted or the undo loop can be prevented from

running at all by passing -1 to initUndo or by setting UndoPeriod to -1.

Class extensions provide simple access to features like control.UpdateUndoStateNow

which can be used for manual updates, or to make the state current before a call to

control.DeleteUndos

Windows and Custom controls can be given undo functionality by utilizing

the CustomUndo class interface

Thanks for trying TheBigUndo!

This software is distributed as-is. Use of this software is without warranty, written

or implied. This software and it's source code are the exclusive intellectual property

of piDog Software.

Purchase of a license allows you to include TheBigUndo and TheBigUndoPreferencesWindow

in your projects and products. A Single User License means one user under one licensed copy of

RealStudio at one time. Multi-User licenses are also available.

Any attempt to reverse-engineer TheBigUndo, attempt to circumvent encryption or licensing or sharing of license keys

will be considered a violation of the license agreement and may be a violation of copyright

laws. piDog Software reserves the right to terminate a violator's license(s) and to prosecute any

such violation.

Copyright piDog Software 2012-2018

TheBigUndo may be licensed for use and distribution in applications built using Xojo by Xojo inc.

A license allows use by the registered developer only. Additional licenses must be purchased for each

additional developer.

Any attempt to break or bypass TheBigUndo's encryption will be a violation of this agreement.

Any attempt to reverse engineer TheBigUndo will be a violation of this agreement.

Sharing, selling or any other form of distributing a license key, intentional or accidental will be

a violation of this agreement.

Any violation of this agreement will result in the termination of the licensee's right to include TheBigUndo in

any applications.

Copyright 2012-2018 piDog Software.

1.1

Added ability to set a Xojo dictionary as a preferences value (encoded as a dictionary)

Added UndoMenuItem class to allow for direct modification of menu text

Menu references now handled more cleanly internally

added shutDownUndos to ensure clean app quit

Fixed a nilobjectexpection using PreferencesDoc on win32

Tested for 64bit compatibility

1.0.4.3

Updated for Xojo 2014r3

Removed external images from demo app.

1.0.4.2

Fixed a bug when building an app

1.0.4.1

Fixed a bug causing a KeyNotFoundException when RadioButtons were placed on a ContainerControl

1.0.4

Added Undo and Redo methods to the module to allow manually calling Undo/Redo actions from code

Added TheBigUndo_StateChangedNotifier interface to allow creation of custom controls to invoke undos

1.0.3.1

Fixed a possible KeyNotFoundException related to ContainerControls

1.0.3

ContainerControls are now detected automatically!

Listbox now supported in window.xml

ListBox RowPicture now supported in undo/redo and window.xml

Updated Documentation and Demo.

1.0.2.6

Now Xojo compaible!

Fixed a bug where undos in Styled TextAreas could become garbled if styled text was copied and pasted repeatedly.

1.0.2.5:

Fixed GTK lib calls to work under Ubuntu 12.10 and other current linux flavors

1.0.2.4:

Minor internal efficiency improvements

If UndosAreManual is set for a control, the control is now checked before the Undo Menu is enabled

Added UndoSetsContentsChangedFlag extension to Window Class

Added a Cocoa workaround for sliders to handle setting a value of 0 in an undo/redo

1.0.2.3

Made some improvements in listbox behavior where an object in a tag is an unknown type (ie plugin class) it is ignored

Listbox checkboxes are now undoable.

Dictionaries and Tag (celltag, rowtag) Picture values now more efficient.

1.0.2.2:

Fixed some issues with the demo project file

1.0.2.1:

Fixed a bug with UndoInFrontWindowOnly that prevented undos in non-document windows

Now correctly ignores all non-undoable controls

Made the Module an internal item in the demo project

1.0.2:

Rearranged Modules and supporting items items so they can be used as external items.

Fixed a bug causing container controls not to be checked correctly.

1.0.1.1:

Fixed a bug causing demo to crash on Linux when viewing methods/properties

1.0.1:

Fixed a Cocoa bug in TextAreas

Renamed internal calls to avoid conflicts with globals in other modules

1.0.0:

Redesigned Styled TextArea Undo handling. CPU usage is now negligible under normal conditions.

Win32 TextArea's no longer "jump around" during undo's

Removed multi-threaded operations to avoid rare, yet possible, crashes.

Updated documentation accordingly.

Fixed UpdateUndoStateNow to clear any pending redo's

Fixed a glitch in the contacts list demo

Moved everything into one Module for ease of use.

CustomUndo interface is now TheBigUndo_CustomUndo interface.

Added documentation to methods inside TheBigUndo module.

Fixed a possible Cocoa crashing bug with control.handle.

TheBigUndo.Init now blocks from being called from multiple locations.

RadioButtons now undo as groups rather than individual controls.

Now handles multibyte characters properly.

TextAreas and TextFields now select text added in an undo or redo action.

Added AddUndoMenuToMenuBar(theMenuBar) for use with multiple menubar apps.

Added SetsContentChangedFlags property to control setting the ContentsChanged flag for windows with available Undo's

Added an XML extension to the window class. Allows getting and setting window state to and from XML.

Added a ClearUndos flag to XML setter to allow users to back out of a "Default Settings" action. ie Preferences Windows.

Added "View"/"Window as XML" menu to the demo project.

Added Window.SimpleDictionary for easy (and multithreaded) access to TheBigUndo_PreferenceWindow values.

Added an internal Cocoa Wrapper class to eliminate some memory leaks.

Added default ListBox Undo handling.

ContactsDemo now uses default Listbox Undo's.

Added Window.SavedState property to allow specifying a state where a window's ContentChanged will be false

1.0.0b3:

CustomUndo now works again.

Fixed a situation that could cause container controls to not record undo's

Removes all references to controls in closed windows

Now completely ignores all non-undoable controls

Demo now sets IgnoreUndos in the main demo window

Demo now sets MonitorFrontWindowOnly

Demo now calls PauseUndoChecking on deactivate and ResumeUndoChecking on activate

Added a throttle to increase checking delay in cpu heavy controls

Calling Window.UpdateUndoStateNow now works as intended again

Improved initial state capture for newly opened windows

Reworked some other state tracking during undo's for more reliability and speed

Reduced CPU usage some more.

Minor edits to documentation.

1.0.0b2:

Updated documentation for CustomUndo Interface.

Now ignores textfields where password=true

Fixed a delay when calling control.DeleteUndos()

Changed CustomUndo Function names to begin with CustomUndo_

Fixed a crashing bug under Cocoa. controlMacControlHandleGetter

Added a more in depth Custom TextArea example.

1.0.0b1:

Initial beta release

An XSL Style for readable XML.

Adds Undo and Redo MenuItems to a MenuBar

Clears all recorded redo actions

Clears redo's for a given control

Clears recorded redo's for a given window

Clears all recorded Undo actions

Clears all Undo's for a gven control

Clears all Undo's for a given window

This Method will return a Dictionary previously saved to the user's preferences

This Method will return a previously saved XmlDocument saved to the user's preferences

Returns true if there are Undo's for the given control

Stops/Starts checking for undo's for the given control

Stops/Starts checking for undo's for the given window

Starts up the undo module. Period is 1/1000ths of a second for the undo loop to run. Pass -1 to trigger all undo testing manually.

Sets the maximum number of undo actions to be recorded

Sets the maximum number of undo's to be recorded for a given control.

Sets the maximum number of undo's to be recorded for a given window.

Stops the undo testing loop after allowing the background thread to finish any current task. Useful when performing other cpu intensive tasks.

Invokes the next available Redo

A method to enter registration info and remove the registration warning message in compiled apps.

Resumes undo testing after a call to PauseUndoChecking

Gets the last XmlDocument set via Window.SavedState=XMLDocument

Sets an XMLDocument as received from then XML property as the currently

saved state of the window so that the window's ContentChanged flag can be

set when the current window state varies from the saved state.

This Method will save a Dictionary as an XmlDocument to the user's preferences

This Method will save an XmlDocument to the user's preferences

Call this in App.Close to clean up event handlers and allow proper app shutdown.

This Function returns a Dictionary containing the basic values of basic controls. CustomUndos and ContainerControls are excluded.

Included for use in TheBigUndo_PreferenceWindow example, and similar uses.

Invokes the next available Undo

Set this to true to exclude a control from the undo testing loop.

Set this to true to exclude a control from the undo testing loop.

Set this to true to exclude a window from the undo testing loop.

Set this to true to exclude a window from the undo testing loop.

Gets whether available undos cause the changed flag to be set for the window.

Sets whether available undos cause the changed flag to be set for the window.

Passing True will tag the Control for testing on the next loop when UndosAreManual has been set.

Passing True will tag the window for testing on the next loop when UndosAreManual has been set.

Call to start a new run of the undo testing loop.

Will run the undo tests on a given Control.

Will run the undo tests on a given Window.

Gets the state of a window as XML.

For CustomUndo controls, pictures are Base64 Encoded PNG's at 100% quality setting.

Array's and Dictionaries are also supported

StyledTextAreas are stored as Base64 Encoded RTF

MemoryBlocks are stored as Base64 Encoded Strings

To add additional tags for use by your app add tags at the top level with a name other than "Document"

Sets the state of a window from an XmlDocument as return by the XML getter Function.

Use XmlDocument.Transform(XSLReadable) for an easy to view Document.

Use CUndos in the case of a preferences window setting to defalt setting or the like.

MyWindow.XML=SavedDoc or MyWindow.XML(false)=SavedDoc

Sets a control to be ignored (or not ignored) when getting a window's state as XML

This property determines whether TheBigUndo will track all windows, or exclusively track the frontmost document window to save cpu cycles.

Default is true

Use this property to set and get and XmlDocument representing your

app's Preference Window.

Default locations are

Win32

~/[appname]_preferences/[appname]_preferences

folder's visible property is set to false

Linux

~/.[appname]_preferences

Mac OSX

saved as an entry in ~/Library/Preferences/[app identifier].plist

with the key "PreferenceWindowSettings"

Be sure to set your app identifier or nothing will be saved!

You can override these by using GetPreferencesDoc and SetPreferencesDoc and passing a FolderItem(Win32/Linux) or Key String(MacOS),

this also allows for multiple preference windows.

Prevents TheBigUndo from performing undos in windows that are not in focus.

Pending Undos will be available when said window gains focus.

Default is true.

This property sets the frequency of undo checking. Value is 1/1000th of a second.

Default is 1000

The CustomUndo interface can be implemented by any control or window.

This interface overrides the default checking and undo implementation.

CustomUndo is mostly intended for controls that do not have standardized data (ie. Listboxes)

This could also be useful for custom controls such as a color chooser or a drawing control.

1) Add CustomUndo to the control or window's interfaces.

2) CustomUndo_GetCurrentState should return a dictionary representing the current state of the control or window.

This will be a dictionary with any number of key/value pairs representing any arbitrary data including pictures.

3) CustomUndo_CheckForStateChange will be passed the most recent state object to be compared with the current state.

if the state has changed return a dictionary describing the change(s), otherwise return nil.

Include an "Undo Type" key with a label to be shown in the UndoMenuItem and RedoMenuItem if you like.

4) CustomUndo_SetCurrentState will be passed the last Dictionary returned by CustomUndo_CheckForStateChange when the user

selects "Undo" from the edit menu.

5) After the undo has been executed, CustomUndo_CheckForStateChange will be called again to obtain the redo dictionary.

if redo is impossible, return nil.

When using this module with controls that use large data, such as an image editor, either only the changed

portion of the image should be returned or the undo levels should be limited to a reasonable amount by setting

control.MaximumUndos

Allows creation of a dictionary describing changes in state. Return nil if no changes were found.

Should return a dictionary desribing the current state of the implementor.

Called when an undo or redo is invoked. StateDictionary is the dictionary returned from CheckForStateChanges

TheBigUndo_StateChangedNotifier is an interface that can be implemented by any class.

The methods will be called with the text describing the Undo/Redo state and a boolean value to determine if there is an Undo/Redo available.

Called when the Redo state has changed. RedoText is the text the user should see, Active is whether a Redo is available.

Called when the Undo state has changed. UndoText is the text the user should see, Active is whether an Undo is available.

UndoMenuItem can be subclassed to implement custom texts for undo and redo functions

The class has one event, UpdateMenuText which will be called with the new text, state and the

control whos state change will be undone/redone.

Return true from the event if you've handled setting the text and state.

To use a subclass, pass an instance/instances to TheBigUndo.AddUndoMenuToMenuBar