
.. _wxwidgets-page:

###############################
|ProductName| with wxWidgets
###############################

.. image:: ../../images/wxwidgets.png
    :height: 64
    :align: right


We provide ready to use platform integration to wxWidgets (https://www.wxwidgets.org/). This page describes how to 
integrate |ProductName| with wxWidgets (https://www.wxwidgets.org/) and how to get your application up and
running with wxWidgets. 

The platform integration classes have been tested using wxWidgets 3.x. On Linux, the integration classes require 
the wxGTK port of wxWidgets.

*****************
Creating a Viewer
*****************

All HOOPS Envision apps need one (or more) viewers in order to visualize the 3D data. We provide two example 
implementations that you can find in the **PlatformIntegration/Wx** folder of the distribution. Both implementations 
derive from wxGLCanvas (and from cee::vis::ViewerUIFramework).

-   **ViewerCanvas:** ceewxViewerCanvas.h/cpp |br|
    This class implements a minimal viewer in wxWidgets. It provides the necessary code for creating, rendering and 
    deleting the viewer. There is no support for navigation/picking etc., just the bare minimum. To create your own Viewer,
    you should derive from this class.

-   **ViewerCanvasDemo:** ceewxViewerCanvasDemo.h/cpp |br|
    This is a demo application oriented implementation which adds Envision style navigation in addition to what is 
    in ViewerCanvas. It is used in the WxMinimal and WxMultiView examples which you can find in the **Examples/Wx** 
    folder of the distribution. The class derives from ViewerCanvas and can be a good starting point for a Viewer 
    in your own application. We recommend copying the source code of this Viewer and modifying it to suit the needs 
    of your application.

ViewerCanvas (and ViewerCanvasDemo) uses a two-stage creation process. After the instance has been created using new,
the ViewerCanvas::initializeViewer() member function must be called before the viewer is used. On Linux, using 
the wxGTK port of wxWidgets, there is a limitation in that this function may only be called after the window has been
shown on screen, in particular it can't usually be called from the constructor as the window isn't yet shown at this 
moment. Similarly, the ViewerCanvas::shutdownViewer() member function should be called before the window is destroyed.
Please see the source code in the WxMinimal and WxMultiView examples for details on how this can be accomplished.

****************
Example Programs
****************

A .vcxproj file is included for Windows users. For Linux users a Makefile for GNU Make is provided.

The Windows .vcxproj file relies on the environment variable **WXWIN** being set to the folder where you have installed 
wxWidgets. 


On Linux, the provided Makefile relies on the **wx-config** utility for obtaining the compiler options, include paths 
and link libraries. This means that **wx-config** must be available in the search path when running make. If you have 
correctly installed wxWidgets this should already be configured. If you have manually compiled wxWidgets without running 
install, you may have to add the directory manually, e.g.

::

    export PATH=/full/path/to/that/wx-config:$PATH


**WxMinimal**

.. |img1| image:: ../../images/example_wx_minimal.png
   :width: 150

+-----------------------+------------------------------------------------------------------------------------+
| |img1|                | **Location**\ : Examples/Wx/WxMinimal |br|                                         |
|                       | A very small example showing the basic requirements for a wxWidgets application.   |
+-----------------------+------------------------------------------------------------------------------------+


**WxMultiView**

.. |img2| image:: ../../images/example_wx_multiview.png
   :width: 150

+-----------------------+------------------------------------------------------------------------------------+
| |img2|                | **Location**\ : Examples/Wx/WxMultiView |br|                                       |
|                       | A small example showing how to do multiple views/windows with |br|                 |
|                       | |ProductName| in wxWidgets.                                                        |
+-----------------------+------------------------------------------------------------------------------------+

