Pylon::CPylonImageWindow#

Module: Image Handling Support

Class to manage a pylon image window. More…

#include <pylon/PylonGUI.h>

Public Functions#

Public Attributes#

Protected Attributes#

Detailed Description#

class Pylon::CPylonImageWindow;

Class to manage a pylon image window.

Remark:

• The easiest way to display an image on screen is to use the DisplayImage() global function.
• To use this class, you must explicitly include pylon/PylonGUIIncludes.h in your code. Unlike other pylon headers, the GUI headers will not be included automatically when you include pylon/PylonIncludes.h.

Use this class to manage a pylon image window.

To diplay an image, you need to create and show it first. You can the call SetImage() to let the window display any Pylon image. The following snippet shows how to do this:

CPylonImageWindow win;
// Create the window with winIndex = 1 using default position and size.
// The window will not be visible until Show() has been called.
win.Create(1);
// Set the contents of the window.
win.SetImage(myImage);
// Make the window visible on the screen.
win.Show();

If the user closes the window, it will only be hidden and not truly closed. You can call Show() to make it visible again. The window will be closed (destroyed) when you call Close(). The destructor automatically closes (i.e destroys) the window. To prevent this, you can call Detach() before the object is destroyed. All windows will be closed when PylonTerminate() is called.

Public Functions Documentation#

function CPylonImageWindow#

CPylonImageWindow(
    void
)

Creates an empty CPylonImageWindow object.

Error Safety:

Does not throw C++ exceptions.

To actuall create the window, you must call Create()

function ~CPylonImageWindow#

~CPylonImageWindow(
    void
)

Destroys a CPylonImageWindow object.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This function is thread-safe.

If the window hasn't been closed, it will be closed.

function GetWindowHandle#

HWND GetWindowHandle() const

Returns the window handle (HWND) for the image window.

Return: Returns the native window handle (HWND) for the image window.

Error Safety:

Throws an exception if the window hasn't been created yet or the window has been already closed.

Thread Safety:

This function is thread-safe.

Returns the native window handle of the image window. The handle will become invalid after Close() has been called.

function GetWindowIndex#

inline size_t GetWindowIndex(
    void
) const

Returns the window index handled by this object.

See: IsValid()

Return: Returns the window index stored in this object.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This function is thread-safe.

The index will become valid if you call Create() or Attach(). The index will become invalid when you call Close() or Detach(). Valid window indexes range from 0 to 31.

function IsValid#

bool IsValid(
    void
) const

Returns true if the object holds a valid window index.

Return: Returns true if the objects holds a valid window index. Otherwise, false is returned.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This function is thread-safe.

Returns true if the object holds a valid window index

function Attach#

void Attach(
    size_t winIndex
)

Attaches the window index passed in winIndex to this object.

Parameters:

• winIndex The new window index to attach to this object. Valid window indexes range from 0 to 31.

Error Safety:

Throws an exception if the object already holds a valid window index. If you want to reuse an existing object, you should call Detach() or Close() to clear the object.

Thread Safety:

This function is thread-safe.

function Detach#

size_t Detach(
    void
)

Detaches the window index from this object and returns the window index previously stored in the object.

Return: Returns the current window index. If no window index is stored, invalidWinIndex will be returned.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This function is thread-safe.

Detaches the window index from this object and returns the window index previously stored in the object. After this function returns the state of the object will be invalid.

You can call this function to prevent the window being closed when the CPylonImageWindow is destroyed. If you don't close a CPylonImageWindow, it will be closed automatically when PylonTerminate() is called.

function Create#

void Create(
    size_t winIndex,
    int x =useDefault,
    int y =useDefault,
    int nWidth =useDefault,
    int nHeight =useDefault
)

Creates a window for index passed in winIndex.

Parameters:

• winIndex The window used for displaying the image. Valid window indexes range from 0 to 31.
• x The x-coordinate of the upper-left corner of the window in screen coordinates. You can pass the CPylonImageWindow::useDefault value to create the window at the same position as the previous one before it was closed. The other position parameters will be ignored. If the window is shown the very first time the system select a default position and size for the window.
• y The y-coordinate of the upper-left corner of the window in screen-coordinates.
• nWidth The width of the window in screen coordinates.
• nHeight The height of the window in screen coordinates.

Error Safety:

• Will throw an exception if an invalid winIndex is passed.
• Will throw an exception if the a window with the specified window index already exists.

Thread Safety:

This function is thread-safe.

Creates a window for the index passed in winIndex. If there is already an existing window with winIndex, an exception will be thrown.

When you pass the CPylonImageWindow::useDefault for the x parameter, the window will be shown at the same position and with the same size as the previous one before it was closed. Otherwise, the position and size parameters are passed directly to the CreateWindow() function of the Windows API.

When the function returns successfully, the window has been created but is not visible. You must call Show() to make the window visible.

function Show#

void Show(
    int nShow =showDefault
) const

Shows or hides the image window.

Remark: After you create a window using Create() it will be invisible. You must call Show() to make the window visible.

Error Safety:

Throws an exception if the window hasn't been created yet and the object doesn't hold a valid window index.

Thread Safety:

This function is thread-safe.

This function calls ShowWindow from the Windows API. You can pass the same values for the nShow parameter as described in the official documentation for ShowWindow() The default value nShowDefault (which equals SW_SHOW) will show the window in its current state and position.

When the user closes the window it will be hidden, but not destroyed. You can call Show() to make it visible again.

function Hide#

void Hide(
    void
) const

Hides the image window.

See: Show()

Error Safety:

Throws an exception if the window hasn't been created yet and the object doesn't hold a valid window index.

Thread Safety:

This function is thread-safe.

This is a convenience function to hide the window. It will call Show(SW_HIDE)

function Close#

bool Close(
    void
)

Closes and destroys the window.

Remark: If you just want to hide the window from the user you should call Hide() instead.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This function is thread-safe.

Closes and destroys the window. When the function returns successfully, the object will be invalid and the stored window index will be set to invalid.

If you don't close a CPylonImageWindow, it will be closed automatically when PylonTerminate() is called.

function SetImage#

void SetImage(
    const Pylon::IImage & image
)

Sets the contents of the image window.

Parameters:

• image The image to display in the window.

Error Safety:

Throws an exception if the window hasn't been created yet and the object doesn't hold a valid window index.

Thread Safety:

This function is thread-safe.

Use this function to set the image shown in the window. You can pass any IImage based object (like CPylonImage or CPylonBitmapImage). You can also pass a GrabResultPtr object as it will convert its contents automatically to an IImage.

If you pass an empty or invalid image the contents of the image window will be cleared.

Public Attributes Documentation#

variable useDefault#

static const int useDefault = static_cast<int>(0x80000000);

Default value for window position/size when calling Create()

variable showDefault#

static const int showDefault = 5;

Default value for window position/size when calling Show()

Protected Attributes Documentation#

variable invalidWinIndex#

static const size_t invalidWinIndex = static_cast<size_t>(-1);

Invalid window index.

variable m_winIndex#

size_t m_winIndex;

The window index managed by this object. Valid window indexes range from 0 to 31. If no window is currently managed, invalidWinIndex will be stored.