wx.NET Documentation

0.9.1

This document describes the API to wx.NET. This is complete referring to the synopsis of classes and methods since it is generated directly from source code. Unfortunately, several classes and functions are not yet described. In these cases, refer to the original wxWidgets documentation. Usually, wx.NET provides the same entities as wxWidgets does, for instance class wxWindow in wxWidgets is wrapped by a class wx.Window in wx.NET and method wx.Window.Show() wrapps method wxWindow.Show().

If you start working with wx.NET, please consult Known Problems And Pitfalls.

Since Release 0.9.1 several methods changed their signature, so you probably will have to adjust existing code. These changes have been motivated by the goal to make wx.NET a real .NET library rather than a more or less complete binding of wxWidgets. So, wx.NET will use enumerations with attribute Flags like wx.WindowStyles instead of unsigned integers whereever possible in order to represend flags and styles. This eases use of the library dramatically since developers can use IntelliSense to list viable options on typing in methods.

The classes of wx.NET have been reorganized into several namespaces like wx.GridCtrl. This eases use of IntelliSense and navigation through the classes using the object manager.

Some concepts of wxWidgets simply do not fit into the .NET world like e.g. validators. Refer to wx.ComponentModel instead.

Refer to Building From Source for notes on how to build wx.NET.

History

• 0.9.1: The main objectives of this release have been a .NET appeal of the library and reliability. All memory allocation actions will now be entered through a monitor since memory management in Windows is not thread safe. Classes have been reorganized into several namespaces like e.g. wx.GridCtrl. Style flags for windows (refer to wx.WindowStyles) and sizers are now enumerations. So, you can use IntelliSense when using controls and sizers. wx.StyledText, wx.Globalization, and wx.MaskedEdit have been added.

• 0.8.0: The main objectives of this release have been documentation and reliability. Utility helpview.exe has been added to the distribution in order to present platform independent HTB documentations on wx.NET, the samples and the original wxWidgets library. Unfortunately, programmers often have to consult the original documentation since the new wx.net.htb file is far from being complete. The text of this documentation is directly compiled from the C# source files. Additionally, a .NET XML documentation can be compiled from these remarks on the source code. Furthermore, this release introduces wx.Archive, the first pure .NET implementation of wx.NET. Many small changes on drawing, fonts, colours, and several controls increased reliability of the system.

Known Problems And Pitfalls

All samples run fine. The status of the implementation is considered stable.

• Always create the thread initializing a wx.NET application (class wx.NET) as STA thread (e.g. using the STAThreadAttribute on the entry point/ main function). wxWidgets as well as .NET will conduct OLE initialization and these initializations must be done consistently.
• Instances of wx.Object (or inheritors) shall only be generated within constructors or methods. I don't know why, but construction of instances of member variables directly with the declaration of that member variable caused access violations on subsequent constructor calls.
• When using device contexts (e.g. wx.Object.PaintDC) you have to dispose the context explicitely immediately after using it. You may either use keyword using to inform .NET to dispose the object immediately after leaving the block (this is equivalent to the standard behavious in C++) or you may call wx.Object.Dispose() explicitely on the device context.
• Applications often replace one control by another. For instance, one might have to add an editor into a static box depending on the type of the data to edit. In C++ implementations of such controls rely on the implicit call of wxWindow.Destroy() by the destructor. In .NET, destruction of objects will usually be deferred. So, wx.Window.Destroy() must be called explicitely to destroy a control that shall be replaced by another. As an examply refer to wx.HtmlWidgetCell that register themselves at the wx.HtmlWindow when they are inserted into that window. When a new page is loaded into that window, these widgets cells and the contained controls are no longer needed. The wx.HtmlWindow can destroy them automatically because they registered themselves.
• By default, wx.NET collects all generated wrappers into a static list of instances (with the exception of strings). Thus, you will have to release all instances of wx.Object explicitely using wx.Object.Dispose() in order to avoid memory leaks, since the wrappers will live until the system is sure that wxWidgets will not need their letter in the further more. Refer to wx.Object.InstancesCount and wx.Object.SavedInstancesCount to test this.
• Use wx.ColourDatabase.TheColourDatabase, wx.Pen.ThePenList, wx.Brush.TheBruchList, and wx.Font.TheFontList whenever possible. Get pens, brushes, and fonts from a window only once and cache them in a member variable.
• Traditionally, wxWidgets often uses bit vectors represented by cardinal numbers to represent configurations and styles of controls. Unfortunately, most styles are not represented by a constant of a particular data type like an enumeration but as a general uint. This practice unfortunately disables editor features like IntelliSence. Refer to files Defs.cs ans Window.cs for the most globally used styles and IDs. At some places, uint styles have been replaced by enumerations (refer to wx.ListCtrl). Use wx.WindowStyles for style flags of windows.
• Sometimes, destructors are used in wxWidgets samples to replace on control by another. Refer to the samples on list boxes wx.Samples.ListCtrlApp and wx.Samples.MyHtmlListBox. Since the .NET framework uses an automatic memory management, use method wx.Window.Destroy() to eliminate the old window before adding the new one.
• Refer to wx.Config.

---