Kodi Documentation 22.0
Kodi is an open source media player and entertainment hub.
Loading...
Searching...
No Matches
1. GUI window (kodi::gui::CWindow)

Class: kodi::gui::CWindow

Main window control class
The addon uses its own skin xml file and displays it in Kodi using this class. More...

Topics

 Definitions, structures and enumerators
 Library definition values
Additional values, structures and things that are used in the Window class.
 
 Callback functions from Kodi to add-on
 GUI window callback functions.
Functions to handle control callbacks from Kodi
 

Functions

 kodi::gui::CWindow::CWindow (const std::string &xmlFilename, const std::string &defaultSkin, bool asDialog, bool isMedia=false)
 Class constructor with needed values for window / dialog.
 
bool kodi::gui::CWindow::Show ()
 Show this window.
 
void kodi::gui::CWindow::Close ()
 Closes this window.
 
void kodi::gui::CWindow::DoModal ()
 Display this window until close() is called.
 
bool kodi::gui::CWindow::SetFocusId (int controlId)
 Gives the control with the supplied focus.
 
int kodi::gui::CWindow::GetFocusId ()
 Returns the id of the control which is focused.
 
void kodi::gui::CWindow::SetControlLabel (int controlId, const std::string &label)
 To set the used label on given control id.
 
void kodi::gui::CWindow::SetControlVisible (int controlId, bool visible)
 To set the visibility on given control id.
 
void kodi::gui::CWindow::SetControlSelected (int controlId, bool selected)
 To set the selection on given control id.
 
void kodi::gui::CWindow::SetProperty (const std::string &key, const std::string &value)
 Sets a window property, similar to an infolabel.
 
std::string kodi::gui::CWindow::GetProperty (const std::string &key) const
 Returns a window property as a string, similar to an infolabel.
 
void kodi::gui::CWindow::SetPropertyInt (const std::string &key, int value)
 Sets a window property with integer value.
 
int kodi::gui::CWindow::GetPropertyInt (const std::string &key) const
 Returns a window property with integer value.
 
void kodi::gui::CWindow::SetPropertyBool (const std::string &key, bool value)
 Sets a window property with boolean value.
 
bool kodi::gui::CWindow::GetPropertyBool (const std::string &key) const
 Returns a window property with boolean value.
 
void kodi::gui::CWindow::SetPropertyDouble (const std::string &key, double value)
 Sets a window property with double value.
 
double kodi::gui::CWindow::GetPropertyDouble (const std::string &key) const
 Returns a window property with double value.
 
void kodi::gui::CWindow::ClearProperties ()
 Remove all present properties from window.
 
void kodi::gui::CWindow::ClearProperty (const std::string &key)
 Clears the specific window property.
 
void kodi::gui::CWindow::MarkDirtyRegion ()
 To inform Kodi that it need to render region new.
 
void kodi::gui::CWindow::ClearList ()
 Function delete all entries in integrated list.
 
void kodi::gui::CWindow::AddListItem (const std::shared_ptr< CListItem > &item, int itemPosition=-1)
 To add a list item in the on window integrated list.
 
void kodi::gui::CWindow::AddListItem (const std::string &item, int itemPosition=-1)
 To add a list item based upon string in the on window integrated list.
 
void kodi::gui::CWindow::RemoveListItem (int itemPosition)
 Remove list item on position.
 
void kodi::gui::CWindow::RemoveListItem (const std::shared_ptr< CListItem > &item)
 Remove item with given control class from list.
 
std::shared_ptr< CListItemkodi::gui::CWindow::GetListItem (int listPos)
 To get list item control class on wanted position.
 
void kodi::gui::CWindow::SetCurrentListPosition (int listPos)
 To set position of selected part in list.
 
int kodi::gui::CWindow::GetCurrentListPosition ()
 To get current selected position in list.
 
int kodi::gui::CWindow::GetListSize ()
 To get the amount of entries in the list.
 
void kodi::gui::CWindow::SetContainerProperty (const std::string &key, const std::string &value)
 Sets a container property, similar to an infolabel.
 
void kodi::gui::CWindow::SetContainerContent (const std::string &value)
 Sets the content type of the container.
 
int kodi::gui::CWindow::GetCurrentContainerId ()
 Get the id of the currently visible container.
 

Detailed Description

Class: kodi::gui::CWindow

Main window control class
The addon uses its own skin xml file and displays it in Kodi using this class.

The with #include <kodi/gui/Window.h> included file brings support to create a window or dialog on Kodi.

The add-on has to integrate its own callback functions in order to process the necessary user access to its window.


Window header example:

<?xml version="1.0" encoding="UTF-8"?>
<window>
<onload>RunScript(script.foobar)</onload>
<onunload>SetProperty(foo,bar)</onunload>
<defaultcontrol always="false">2</defaultcontrol>
<menucontrol>9000</menucontrol>
<backgroundcolor>0xff00ff00</backgroundcolor>
<views>50,51,509,510</views>
<visible>Window.IsActive(Home)</visible>
<animation effect="fade" time="100">WindowOpen</animation>
<animation effect="slide" end="0,576" time="100">WindowClose</animation>
<zorder>1</zorder>
<coordinates>
<left>40</left>
<top>50</top>
<origin x="100" y="50">Window.IsActive(Home)</origin>
</coordinates>
<previouswindow>MyVideos</previouswindow>
<controls>
<control>
</control>
....
</controls>
</window>

On functions defined input variable controlId (GUI control identifier) is the on window.xml defined value behind type added with id="..." and used to identify for changes there and on callbacks.

<control type="label" id="31">
<description>Title Label</description>
...
</control>
<control type="progress" id="32">
<description>progress control</description>
...
</control>

Function Documentation

◆ AddListItem() [1/2]

void kodi::gui::CWindow::AddListItem ( const std::shared_ptr< CListItem > & item,
int itemPosition = -1 )
inline

To add a list item in the on window integrated list.

Parameters
[in]itemList item to add
[in]itemPosition[opt] The position for item, default is on end

◆ AddListItem() [2/2]

void kodi::gui::CWindow::AddListItem ( const std::string & item,
int itemPosition = -1 )
inline

To add a list item based upon string in the on window integrated list.

Parameters
[in]itemList item to add
[in]itemPosition[opt] The position for item, default is on end

◆ ClearList()

void kodi::gui::CWindow::ClearList ( )
inline

Function delete all entries in integrated list.

◆ ClearProperties()

void kodi::gui::CWindow::ClearProperties ( )
inline

Remove all present properties from window.

◆ ClearProperty()

void kodi::gui::CWindow::ClearProperty ( const std::string & key)
inline

Clears the specific window property.

Parameters
[in]keystring - property name.
Note
Key is NOT case sensitive. Equivalent to SetProperty(key, "") You can use the above as keywords for arguments and skip certain optional arguments. Once you use a keyword, all following arguments require the keyword.

Example:

..
ClearProperty('Category')
..
void ClearProperty(const std::string &key)
Clears the specific window property.
Definition addons/kodi-dev-kit/include/kodi/gui/Window.h:429

◆ Close()

void kodi::gui::CWindow::Close ( )
inline

Closes this window.

Closes this window by activating the old window.

Note
The window is not deleted with this method.

◆ CWindow()

kodi::gui::CWindow::CWindow ( const std::string & xmlFilename,
const std::string & defaultSkin,
bool asDialog,
bool isMedia = false )
inline

Class constructor with needed values for window / dialog.

Creates a new Window class.

Parameters
[in]xmlFilenameXML file for the skin
[in]defaultSkinDefault skin to use if needed not available
[in]asDialogUse window as dialog if set
[in]isMedia[opt] bool - if False, create a regular window. if True, create a mediawindow. (default=false)
Note
isMedia value as true only usable for windows not for dialogs.

◆ DoModal()

void kodi::gui::CWindow::DoModal ( )
inline

Display this window until close() is called.

◆ GetCurrentContainerId()

int kodi::gui::CWindow::GetCurrentContainerId ( )
inline

Get the id of the currently visible container.

Returns
currently visible container id

◆ GetCurrentListPosition()

int kodi::gui::CWindow::GetCurrentListPosition ( )
inline

To get current selected position in list.

Returns
Current list position

◆ GetFocusId()

int kodi::gui::CWindow::GetFocusId ( )
inline

Returns the id of the control which is focused.

Returns
Focused control id

◆ GetListItem()

std::shared_ptr< CListItem > kodi::gui::CWindow::GetListItem ( int listPos)
inline

To get list item control class on wanted position.

Parameters
[in]listPosPosition from where control is needed
Returns
The list item control class or null if not found
Warning
Function returns a new generated CListItem class!

◆ GetListSize()

int kodi::gui::CWindow::GetListSize ( )
inline

To get the amount of entries in the list.

Returns
Size of in window integrated control class

◆ GetProperty()

std::string kodi::gui::CWindow::GetProperty ( const std::string & key) const
inline

Returns a window property as a string, similar to an infolabel.

Parameters
[in]keystring - property name.
Returns
The property as string (if present)
Note
Key is NOT case sensitive. Setting value to an empty string is equivalent to clearProperty(key).
You can use the above as keywords for arguments and skip certain optional arguments.
Once you use a keyword, all following arguments require the keyword.

◆ GetPropertyBool()

bool kodi::gui::CWindow::GetPropertyBool ( const std::string & key) const
inline

Returns a window property with boolean value.

Parameters
[in]keystring - property name.
Returns
boolean value of property

◆ GetPropertyDouble()

double kodi::gui::CWindow::GetPropertyDouble ( const std::string & key) const
inline

Returns a window property with double value.

Parameters
[in]keystring - property name.
Returns
double value of property

◆ GetPropertyInt()

int kodi::gui::CWindow::GetPropertyInt ( const std::string & key) const
inline

Returns a window property with integer value.

Parameters
[in]keystring - property name.
Returns
integer value of property

◆ MarkDirtyRegion()

void kodi::gui::CWindow::MarkDirtyRegion ( )
inline

To inform Kodi that it need to render region new.

◆ RemoveListItem() [1/2]

void kodi::gui::CWindow::RemoveListItem ( const std::shared_ptr< CListItem > & item)
inline

Remove item with given control class from list.

Parameters
[in]itemList item control class to remove

◆ RemoveListItem() [2/2]

void kodi::gui::CWindow::RemoveListItem ( int itemPosition)
inline

Remove list item on position.

Parameters
[in]itemPositionList position to remove

◆ SetContainerContent()

void kodi::gui::CWindow::SetContainerContent ( const std::string & value)
inline

Sets the content type of the container.

Parameters
[in]valuestring or unicode - content value.

Available content types

Name Media
actors Videos
addons Addons, Music, Pictures, Programs, Videos
albums Music, Videos
artists Music, Videos
countries Music, Videos
directors Videos
files Music, Videos
games Games
genres Music, Videos
images Pictures
mixed Music, Videos
movies Videos
Musicvideos Music, Videos
playlists Music, Videos
seasons Videos
sets Videos
songs Music
studios Music, Videos
tags Music, Videos
tvshows Videos
videos Videos
years Music, Videos

◆ SetContainerProperty()

void kodi::gui::CWindow::SetContainerProperty ( const std::string & key,
const std::string & value )
inline

Sets a container property, similar to an infolabel.

Parameters
[in]keystring - property name.
[in]valuestring or unicode - value of property.
Note
Key is NOT case sensitive.
You can use the above as keywords for arguments and skip certain optional arguments.
Once you use a keyword, all following arguments require the keyword.

◆ SetControlLabel()

void kodi::gui::CWindow::SetControlLabel ( int controlId,
const std::string & label )
inline

To set the used label on given control id.

Parameters
[in]controlIdControl id where label need to set
[in]labelLabel to use

◆ SetControlSelected()

void kodi::gui::CWindow::SetControlSelected ( int controlId,
bool selected )
inline

To set the selection on given control id.

Parameters
[in]controlIdControl id where selection is changed
[in]selectedBoolean value with true for selected, false for not

◆ SetControlVisible()

void kodi::gui::CWindow::SetControlVisible ( int controlId,
bool visible )
inline

To set the visibility on given control id.

Parameters
[in]controlIdControl id where visibility is changed
[in]visibleBoolean value with true for visible, false for hidden

◆ SetCurrentListPosition()

void kodi::gui::CWindow::SetCurrentListPosition ( int listPos)
inline

To set position of selected part in list.

Parameters
[in]listPosPosition to use

◆ SetFocusId()

bool kodi::gui::CWindow::SetFocusId ( int controlId)
inline

Gives the control with the supplied focus.

Parameters
[in]controlIdOn skin defined id of control
Returns
Return true if call and focus is successed, if false was something failed to get needed skin parts

◆ SetProperty()

void kodi::gui::CWindow::SetProperty ( const std::string & key,
const std::string & value )
inline

Sets a window property, similar to an infolabel.

Parameters
[in]keystring - property name.
[in]valuestring or unicode - value of property.
Note
Key is NOT case sensitive. Setting value to an empty string is equivalent to clearProperty(key).
You can use the above as keywords for arguments and skip certain optional arguments.
Once you use a keyword, all following arguments require the keyword.

◆ SetPropertyBool()

void kodi::gui::CWindow::SetPropertyBool ( const std::string & key,
bool value )
inline

Sets a window property with boolean value.

Parameters
[in]keystring - property name.
[in]valueboolean value to set

◆ SetPropertyDouble()

void kodi::gui::CWindow::SetPropertyDouble ( const std::string & key,
double value )
inline

Sets a window property with double value.

Parameters
[in]keystring - property name.
[in]valuedouble value to set

◆ SetPropertyInt()

void kodi::gui::CWindow::SetPropertyInt ( const std::string & key,
int value )
inline

Sets a window property with integer value.

Parameters
[in]keystring - property name.
[in]valueinteger value to set

◆ Show()

bool kodi::gui::CWindow::Show ( )
inline

Show this window.

Shows this window by activating it, calling close() after it will activate the current window again.

Note
If your Add-On ends this window will be closed to. To show it forever, make a loop at the end of your Add-On or use DoModal() instead.
Warning
If used must be the class be global present until Kodi becomes closed. The creation can be done before "Show" becomes called, but not delete class after them.
Returns
Return true if call and show is successed, if false was something failed to get needed skin parts.