wxskinnableframe.h

Powerful and Portable GPS application -- support Linux, Windows, Windows CE GPS navigation and Map m

/*
 *  Roadnav
 *  wxSkinnableFrame.h
 *
 *  Copyright (c) 2004 - 2007 Richard L. Lynch <[e-mail]>
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of version 2 of the GNU General Public License
 *  as published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

//////////////////////////////////////////////////////////////////////////////
/// \file
///
/// Contains the wxSkinnableFrame class and its support code -
/// converts a regular frame into a skinnable one.
///
//////////////////////////////////////////////////////////////////////////////

#ifndef WXSKINNABLEFRAME_H
#define WXSKINNABLEFRAME_H

#include <wx/minifram.h>

#include "tinyxml.h"

#include <vector>
#include <map>
#include <string>

#define TIMER_REFRESH		2

std::vector<wxString> EnumerateSkins();

//////////////////////////////////////////////////////////////////////////////
///
/// \brief This class represents a coordinate that's dependent upon the
/// height/width of the control.
///
/// The formula for used is offset1 + (offset2 + max) * multiplier,
/// where offset1, offset2, and multiplier are constants. Max is
/// the height or width of the control.
///
//////////////////////////////////////////////////////////////////////////////
class wxSkinnableFrame_ProportionalCoordinate
{
	public:
		wxSkinnableFrame_ProportionalCoordinate();
		void Load(TiXmlElement * root);
		int Resolve(int iMax);

		int m_iOffset1;
		int m_iOffset2;
		double m_fMultiplier;
};

//////////////////////////////////////////////////////////////////////////////
///
/// \brief Represents a pair of wxSkinnableFrame_ProportionalCoordinate objects
///
//////////////////////////////////////////////////////////////////////////////
class wxSkinnableFrame_ProportionalPoint
{
	public:
		void Load(TiXmlElement * root);
		wxPoint Resolve(wxPoint cMax);

		wxSkinnableFrame_ProportionalCoordinate m_cX;
		wxSkinnableFrame_ProportionalCoordinate m_cY;
};

//////////////////////////////////////////////////////////////////////////////
///
/// \brief Represents a control that is sized and positioned using a pair
/// of wxSkinnableFrame_ProportionalPoint objects
///
//////////////////////////////////////////////////////////////////////////////
class wxSkinnableFrame_LayoutControl
{
	public:

		wxSkinnableFrame_LayoutControl();
		
		void Position(wxSize szParent);

	public:
		enum EType
		{
			ctControl,
			ctButton,
			ctImage,
			ctText
		};

		wxSkinnableFrame_ProportionalPoint m_coTopLeft;
		wxSkinnableFrame_ProportionalPoint m_coBottomRight;

		EType m_eType;
		wxString m_strName;

		int m_iShowMinHeight;
		int m_iShowMinWidth;
		
		/// If this is greater than or equal to zero, causes the width of this
		/// control to be reduced to m_cCenterWidth, and it to be centered
		/// horizontally at the coordinates specified by m_coTopLeft and
		/// m_coBottomRight
		wxCoord m_cCenterWidth;

		/// Pointer to the control being positioned
		wxControl * m_pControl;


		/// Text to prepend to label
		wxString m_strPrepend;

		/// Text to append to label
		wxString m_strAppend;

		/// Used to decide if control is in active state or not
		wxString m_strActiveKey;
};

//////////////////////////////////////////////////////////////////////////////
///
/// \brief Base class used to make a skinnable frame
///
//////////////////////////////////////////////////////////////////////////////

/**

\section SkinFormat Skin Format

\subsection SkinFormatOverview Overview

Roadnav uses an XML document to describe the layout of the main window. The
XML document, along with all of the images used by the skin are grouped
together into a directory whose name is the name of the skin. The filename
of the XML document is always skin.xml. So, for instance, the skin Default-Day
is described by the XML document residing in Default-Day/skin.xml. All of the
PNG images used by Default-Day are also in the Default-Day directory. The
Default-Day directory itself resides in the skins directory of the Roadnav
installation.

The root element of the skin XML document is always roadnavskin. It has two
child elements - global and layout. Global describes some global attributes,
such as background color and font size. Layout contains one child element
for each element of the skin. A detailed description of each follows.

\subsection SkinFormatGlobalElement Global Element

The global element contains some attributes that affect all of Roadnav. It
supports two child elements at this time - font and minsize. Font is used
to describe the default font used in many places in Roadnav. It has two child
elements describing the font - name and size. The value of the name child is
equal to the desired font name. The value of the size child is equal to the
describe font size in points.

The minsize element describes the minimum size of the Roadnav window when
this skin is in use. Minsize accepts two attributes, width and height,
describing the minimum width and height of the Roadnav window in pixels.

\subsection SkinFormatLayoutElement Layout Element

The layout element contains one child element for each control in the Roadnav
window. It supports four types of controls - buttons, images, text, and
special controls. Z-order is determined by the order of the child elements
in the XML document. The first child element in the document appears on the
bottom, the second appears on top of that, etc. Each type of child element
is described in the following sections.

\subsubsection SkinFormatLayoutButtonElement Button Element

The button element implements a simple momentary button. It has five
attributes - defaultimage, depressedimage, action, activeimage, and activekey. 
Defaultimage indicates the image shown when the button is not pressed. Depressedimage
indicates the image shown when the button is pressed. Activeimage indicates
the image shown when the button is active. Activekey determines when the
button is active.

Action indicates what action should be taken when the button is pressed. 
The following actions are available:

- \b zoomin \n
  Zooms the map in (more detail).
- \b zoomout \n
  Zooms the map out (less detail).
- \b zoom0 through zoom14 \n
  Zooms the map to a specific level.
- \b save \n
  Brings up the dialog to save the current map to a file.
- \b print \n
  Brings up the print dialog.
- \b exit \n
  Exits Roadnav.
- \b setaddress \n
  Brings up the set address dialog box.
- \b getdirections \n
  Brings up the get directions dialog box.
- \b mapmoveleft \n
  Moves the map left 1/4 of a screen.
- \b mapmoveright \n
  Moves the map right 1/4 of a screen.
- \b mapmoveup \n
  Moves the map up 1/4 of a screen.
- \b mapmovedown \n
  Moves the map down 1/4 of a screen.
- \b downloadmaps \n
  Brings up the download maps dialog box.
- \b preferences \n
  Brings up the preferences dialog box.
  
Button also accepts the common children and attributes described 
in a later section.
  
\subsubsection SkinFormatLayoutImageElement Image Element

The image element loads a static image. It accepts one attribute - filename,
which indicates the filename of the static image.

\subsubsection SkinFormatLayoutTextElement Text Element

The text element displays various types of text on the screen. It accepts
four attributes - name, label, prepend, and append. Name indicates the type
of text to be shown. It may take on any of the following values:

- GPS Street
- GPS City
- GPS State
- GPS Full Address
- GPS Speed
- GPS Heading

Label defines the default label to be shown. Prepend and append prepend and 
append text to the information described by the name attribute.

The font child element specifies the font for the text. As before, it has two child
elements describing the font - name and size. The value of the name child is
equal to the desired font name. The value of the size child is equal to the
describe font size in points.

\subsubsection SkinFormatLayoutSpecialElement Special Element

This is used to create special Roadnav defined controls in the skin. The map and 
compass controls are the only such controls at this time. It accepts one 
attribute - name, which indicates the name of the requested control - either 
"map" or "compass".

\subsubsection SkinFormatLayoutCommonChildren Common Children and Attributes of Button, Image, Text, and Special.

Button, image, text, and control also accept other attributes and children. Each should
have a region child describing the region of the main window that the control should
occupy. The region element contains two child elements - topleft and bottomright. Each of
those elements contains two child elements - x and y. X and y have no children but contain
one or more of the following attributes - offset1, offset2, and/or multiplier. The
coordinate specified by x or y is defined by the formula offset1 + (offset2 + max) * multiplier,
where max is the width of the main window for x, or the height of the main window for y.
So for instance, if x is supplied with just an offset1 of 100, then the x coordinate
shall always be 100. On the other hand, if x is supplied with a multiplier of 1, and an offset1
of -100, it will always be 100 pixels from the right edge of the main window.

The bgcolor and fgcolor attribute can be applied to button, image, text, or control
to change the background and/or foreground color of the control. The color should be
specified in #rrggbb format (HTML style).

The showminheight and showminwidth attributes control when a particular control should
be visible. If neither attribute is present, then the control is always visible. If
either or both attributes are present, then the control will only be shown in the size
of the Roadnav main window is equal to or greater than the dimensions supplied.

*/

class wxSkinnableFrame : public wxFrame
{
	public:
		wxSkinnableFrame(wxWindow* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE, const wxString& name = wxT("frame"));
		~wxSkinnableFrame();
		
		bool LoadSkin(wxString strPath, bool bIsFilename);

		void AddNamedControl(wxControl * pCtl, wxString strName);

		void SetNamedText(wxString strName, wxString strNewLabel, bool bNeedLock = true);

		void OnSize(wxSizeEvent & evEvent);
		void OnTimerRefresh(wxTimerEvent& event);
		
		void SetActive(wxString strActiveKey, bool bActive, bool bNeedLock = true);

	protected:

		/// Override this to map a string name of a menu ID
		/// to its numerical ID
		virtual int MapNameToID(wxString strName) = 0;
		
		/// Override this with a function that creates a
		/// control called strName
		virtual void CreateNamedControl(wxString strName);
		virtual void DeleteNamedControl(wxString strName, wxControl * pControl);

	private:

		wxString GetDataFilename(wxString strName);

		bool LoadSkinMainWindow(TiXmlElement * root);

		bool LoadSkinLayout(TiXmlElement * root);
		bool LoadSkinLayoutControl(TiXmlElement * root);
		bool LoadSkinLayoutButton(TiXmlElement * root);
		bool LoadSkinLayoutImage(TiXmlElement * root);
		bool LoadSkinLayoutText(TiXmlElement * root);
		bool LoadSkinGlobal(TiXmlElement * root);

		bool ApplyControlCommonAttributes(TiXmlElement * root, wxSkinnableFrame_LayoutControl * psLayoutControl, wxControl * pControl);
		bool ApplyWindowCommonAttributes(TiXmlElement * root, wxWindow * pWindow);

		void UnloadSkin();

		/// Map of controls that have not been assigned to m_vPositionedControls yet
		std::map<std::string,wxControl *> m_mapUnassignedControls;

		/// Array of controls that have been loaded and positioned by the skin
		std::vector<wxSkinnableFrame_LayoutControl> m_vPositionedControls;

		/// Path to the skin
		wxString m_strSkinPath;

		/// Default font used for this frame
		wxFont m_fntDefault;

		/// Current skin in use
		wxString m_strCurrentSkin;

		wxMutex m_mxSkin;
		
		wxTimer * m_pTimerRefresh;

		DECLARE_EVENT_TABLE()

};

#endif