CUserToolsManager (clase)

Mantiene la colección de objetos Clase CUserTool en una aplicación. Una herramienta de usuario es un elemento de menú que ejecuta una aplicación externa. El objeto CUserToolsManager permite al usuario o al programador agregar nuevas herramientas de usuario a la aplicación. Admite la ejecución de los comandos asociados a las herramientas de usuario y también guarda información sobre las herramientas de usuario en el Registro de Windows.

Sintaxis

class CUserToolsManager : public CObject

Miembros

Constructores públicos

Nombre	Descripción
CUserToolsManager::CUserToolsManager	Construye un objeto CUserToolsManager.

Métodos públicos

Nombre	Descripción
CUserToolsManager::CreateNewTool	Crea una nueva herramienta de usuario.
CUserToolsManager::FindTool	Devuelve el puntero al objeto CMFCUserTool asociado a un id. de comando especificado.
CUserToolsManager::GetArgumentsMenuID	Devuelve el id. de recurso asociado al menú Argumentos de la pestaña Herramientas del cuadro de diálogo Personalizar.
CUserToolsManager::GetDefExt	Devuelve la extensión predeterminada que usa el cuadro de diálogo Archivo abierto (CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogoPersonalizar.
CUserToolsManager::GetFilter	Devuelve el filtro de archivo que usa el cuadro de diálogo Archivo abierto (Clase CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogo Personalizar.
CUserToolsManager::GetInitialDirMenuID	Devuelve el id. de recurso asociado al menú Directorio inicial de la pestaña Herramientas del cuadro de diálogo Personalizar.
CUserToolsManager::GetMaxTools	Devuelve el número máximo de herramientas de usuario que se pueden asignar en la aplicación.
CUserToolsManager::GetToolsEntryCmd	Devuelve el id. de comando del marcador de posición del elemento de menú para las herramientas de usuario.
CUserToolsManager::GetUserTools	Devuelve una referencia a la lista de herramientas de usuario.
CUserToolsManager::InvokeTool	Ejecuta una aplicación asociada a la herramienta de usuario que tiene un id. de comando especificado.
CUserToolsManager::IsUserToolCmd	Determina si un id. de comando está asociado a una herramienta de usuario.
CUserToolsManager::LoadState	Carga información sobre las herramientas de usuario desde el registro de Windows.
CUserToolsManager::MoveToolDown	Mueve la herramienta de usuario especificada hacia abajo en la lista de herramientas de usuario.
CUserToolsManager::MoveToolUp	Mueve la herramienta de usuario especificada hacia arriba en la lista de herramientas de usuario.
CUserToolsManager::RemoveTool	Quita la herramienta de usuario especificada de la aplicación.
CUserToolsManager::SaveState	Almacena información sobre las herramientas de usuario en el registro de Windows.
CUserToolsManager::SetDefExt	Especifica la extensión predeterminada que usa el cuadro de diálogo Archivo abierto (Clase CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogo Personalizar.
CUserToolsManager::SetFilter	Especifica el filtro de archivo que usa el cuadro de diálogo Archivo abierto (Clase CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogo Personalizar.

Comentarios

Para incorporar herramientas de usuario a la aplicación, debe:

1. Reservar un elemento de menú y un id. de comando asociado para una entrada de menú de la herramienta de usuario.

2. Reservar un id. de comando secuencial para cada herramienta de usuario que un usuario pueda definir en la aplicación.

3. Llame al método CWinAppEx::EnableUserTools y proporcione los parámetros siguientes: id. de comando de menú, primer id. de comando de la herramienta de usuario y último id. de comando de la herramienta de usuario.

Solo debería haber un objeto CUserToolsManager global por aplicación.

Para obtener un ejemplo de herramientas de usuario, consulte el proyecto de ejemplo VisualStudioDemo.

Ejemplo

En el ejemplo siguiente se muestra cómo recuperar una referencia a un objeto CUserToolsManager y cómo crear nuevas herramientas de usuario. Este fragmento de código forma parte del ejemplo de demostración de Visual Studio.

CUserToolsManager* pUserToolsManager = theApp.GetUserToolsManager();
if (pUserToolsManager != NULL && pUserToolsManager->GetUserTools().IsEmpty())
{
   // CUserToolsManager* pUserToolsManager
   CUserTool* pTool1 = pUserToolsManager->CreateNewTool();
   pTool1->m_strLabel = _T("&Notepad");
   pTool1->SetCommand(_T("notepad.exe"));

   CUserTool* pTool2 = pUserToolsManager->CreateNewTool();
   pTool2->m_strLabel = _T("Paint &Brush");
   pTool2->SetCommand(_T("mspaint.exe"));

   CUserTool* pTool3 = pUserToolsManager->CreateNewTool();
   pTool3->m_strLabel = _T("&Windows Explorer");
   pTool3->SetCommand(_T("explorer.exe"));

   CUserTool* pTool4 = pUserToolsManager->CreateNewTool();
   pTool4->m_strLabel = _T("Microsoft On-&Line");
   pTool4->SetCommand(_T("http://www.microsoft.com"));
}

Jerarquía de herencia

CObject

CUserToolsManager

Requisitos

Encabezado: afxusertoolsmanager.h

CUserToolsManager::CreateNewTool

Crea una nueva herramienta de usuario.

CUserTool* CreateNewTool();

Valor devuelto

Un puntero a la herramienta de usuario recién creada, o NULL si el número de herramientas de usuario ha superado el máximo. El tipo de valor devuelto es el mismo que el tipo que se pasa a CWinAppEx::EnableUserTools como parámetro pToolRTC.

Comentarios

Este método encuentra el primer id. de comando de menú disponible en el intervalo que se proporciona en la llamada a CWinAppEx::EnableUserTools y asigna este id. a la herramienta de usuario.

Se produce un error en el método si el número de herramientas ha alcanzado el máximo. Esto sucede cuando todos los id. de comando dentro del intervalo se asignan a las herramientas de usuario. Puede recuperar el número máximo de herramientas llamando a CUserToolsManager::GetMaxTools. Puede obtener acceso a la lista de herramientas llamando al método CUserToolsManager::GetUserTools.

CUserToolsManager::CUserToolsManager

Construye un objeto CUserToolsManager. Cada aplicación debe tener como máximo un administrador de herramientas de usuario.

CUserToolsManager();

CUserToolsManager(
    const UINT uiCmdToolsDummy,
    const UINT uiCmdFirst,
    const UINT uiCmdLast,
    CRuntimeClass* pToolRTC=RUNTIME_CLASS(CUserTool),
    UINT uArgMenuID=0,
    UINT uInitDirMenuID=0);

Parámetros

uiCmdToolsDummy
[in] Un entero sin signo que el marco utiliza como marcador de posición para el id. de comando del menú de herramientas de usuario.

uiCmdFirst
[in] Identificador de comando del primer comando de herramientas de usuario.

uiCmdLast
[in] El id. de comando del último comando de herramientas de usuario.

pToolRTC
[in] La clase que crea CUserToolsManager::CreateNewTool crea. Con esta clase, puede usar un tipo derivado de la clase CUserTool en lugar de la implementación predeterminada.

uArgMenuID
[in] El id. de recurso de menú del menú emergente de argumentos.

uInitDirMenuID
[in] El id. de recurso de menú del menú emergente del directorio inicial.

Comentarios

No llame a este constructor. En su lugar, llame a CWinAppEx::EnableUserTools para habilitar las herramientas de usuario y llame a CWinAppEx::GetUserToolsManager para obtener un puntero al CUserToolsManager. Para obtener más información, consulte Herramientas definidas por el Usuario.

CUserToolsManager::FindTool

Devuelve el puntero al objeto clase CUserTool asociado a un id. de comando especificado.

CUserTool* FindTool(UINT uiCmdId) const;

Parámetros

uiCmdId
[in] Un id. de comando de menú.

Valor devuelto

Un puntero a un objeto clase CUserTool o derivado deCUserTool si es correcto; de lo contrario, NULL.

Comentarios

Cuando FindTool es correcto, el tipo de valor devuelto es el mismo que el tipo del parámetro pToolRTC para CWinAppEx::EnableUserTools.

CUserToolsManager::GetArgumentsMenuID

Devuelve el id. de recurso asociado al menú Argumentos de la pestaña Herramientas del cuadro de diálogo Personalizar.

UINT GetArgumentsMenuID() const;

Valor devuelto

El id. de un recurso de menú.

Comentarios

El parámetro uArgMenuID de CWinAppEx::EnableUserTools especifica el id. del recurso.

CUserToolsManager::GetDefExt

Devuelve la extensión predeterminada que usa el cuadro de diálogo Archivo abierto (CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogoPersonalizar.

const CString& GetDefExt() const;

Valor devuelto

Una referencia al objeto CString que contiene la extensión.

CUserToolsManager::GetFilter

Devuelve el filtro de archivo que usa el cuadro de diálogo Archivo abierto (Clase CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogo Personalizar.

const CString& GetFilter() const;

Valor devuelto

Una referencia al objeto CString que contiene el filtro.

CUserToolsManager::GetInitialDirMenuID

Devuelve el id. de recurso asociado al menú Directorio inicial de la pestaña Herramientas del cuadro de diálogo Personalizar.

UINT GetInitialDirMenuID() const;

Valor devuelto

Un id. de recurso de menú.

Comentarios

El id. devuelto se especifica en el parámetro uInitDirMenuID de CWinAppEx::EnableUserTools.

CUserToolsManager::GetMaxTools

Devuelve el número máximo de herramientas de usuario que se pueden asignar en la aplicación.

int GetMaxTools() const;

Valor devuelto

Número máximo de herramientas de usuario que se pueden asignar.

Comentarios

Llame a este método para recuperar el número máximo de herramientas que se pueden asignar en la aplicación. Este número es el número de id. en el intervalo desde el parámetro uiCmdFirst hasta el parámetro uiCmdLast que se pasan a CWinAppEx::EnableUserTools.

CUserToolsManager::GetToolsEntryCmd

Devuelve el id. de comando del marcador de posición del elemento de menú para las herramientas de usuario.

UINT GetToolsEntryCmd() const;

Valor devuelto

El id. de comando del marcador de posición.

Comentarios

Para habilitar las herramientas de usuario, llame a CWinAppEx::EnableUserTools. El parámetro uiCmdToolsDummy especifica el id. de comando del comando de entrada de herramientas. Este método devuelve el id. del comando de entrada de las herramientas. Siempre que se utilice ese id. en un menú, se reemplazará por la lista de herramientas de usuario cuando aparezca el menú.

CUserToolsManager::GetUserTools

Devuelve una referencia a la lista de herramientas de usuario.

const CObList& GetUserTools() const;

Valor devuelto

Referencia const a un objeto de clase CObList que contiene una lista de herramientas de usuario.

Comentarios

Llame a este método para recuperar una lista de las herramientas de usuario que mantiene el objeto CUserToolsManager. Cada herramienta de usuario se representa mediante un objeto de tipo clase CUserTool o un tipo derivado desde CUserTool. El tipo se especifica mediante el parámetro pToolRTC cuando se llama a CWinAppEx::EnableUserTools para habilitar las herramientas de usuario.

CUserToolsManager::InvokeTool

Ejecuta una aplicación asociada a la herramienta de usuario que tiene un id. de comando especificado.

BOOL InvokeTool(UINT uiCmdId);

Parámetros

uiCmdId
[in] El id. del comando de menú asociado a la herramienta de usuario.

Valor devuelto

Distinto de cero si el comando asociado a la herramienta de usuario se ejecutó correctamente; de lo contrario, 0.

Comentarios

Llame a este método para ejecutar una aplicación asociada a la herramienta de usuario que tiene el id. de comando especificado por uiCmdId.

CUserToolsManager::IsUserToolCmd

Determina si un id. de comando está asociado a una herramienta de usuario.

BOOL IsUserToolCmd(UINT uiCmdId) const;

Parámetros

uiCmdId
[in] Un id. de comando del elemento de menú.

Valor devuelto

Distinto de cero si un determinado id. de comando está asociado a una herramienta de usuario; de lo contrario, 0.

Comentarios

Este método comprueba si el id. de comando especificado está en el intervalo de id. de comando. Especifique el intervalo al llamar a CWinAppEx::EnableUserTools para habilitar las herramientas de usuario.

CUserToolsManager::LoadState

Carga información sobre las herramientas de usuario desde el registro de Windows.

BOOL LoadState(LPCTSTR lpszProfileName=NULL);

Parámetros

lpszProfileName
[in] La ruta de acceso de la clave del registro de Windows.

Valor devuelto

Distinto de cero si el estado se cargó correctamente; de lo contrario, 0.

Comentarios

Este método carga el estado del objeto CUserToolsManager desde el registro de Windows.

Normalmente no se llama a este método directamente. CWinAppEx::LoadState lo llama como parte del proceso de inicialización del área de trabajo.

CUserToolsManager::MoveToolDown

Mueve la herramienta de usuario especificada hacia abajo en la lista de herramientas de usuario.

BOOL MoveToolDown(CUserTool* pTool);

Parámetros

pTool
[in] Especifica la herramienta de usuario que se moverá.

Valor devuelto

Distinto de cero si la herramienta de usuario se ha movido hacia abajo correctamente; de lo contrario, 0.

Comentarios

Se produce un error en el método si la herramienta que especifica el parámetro pTool no está en la lista interna o si la herramienta es la última de la lista.

CUserToolsManager::MoveToolUp

Mueve la herramienta de usuario especificada hacia arriba en la lista de herramientas de usuario.

BOOL MoveToolUp(CUserTool* pTool);

Parámetros

pTool
[in] Especifica la herramienta de usuario que se moverá.

Valor devuelto

Distinto de cero si la herramienta de usuario se ha movido hacia arriba correctamente; de lo contrario, 0.

Comentarios

Se produce un error en el método si la herramienta que especifica el parámetro pTool no está en la lista interna o si la herramienta es el primer elemento de la lista.

CUserToolsManager::RemoveTool

Quita la herramienta de usuario especificada de la aplicación.

BOOL RemoveTool(CUserTool* pTool);

Parámetros

pTool
[in, out] Un puntero a una herramienta de usuario que se va a quitar.

Valor devuelto

TRUE si la herramienta se quita correctamente. De lo contrario, FALSE.

Comentarios

Si la herramienta se quita correctamente, este método elimina pTool.

CUserToolsManager::SaveState

Almacena información sobre las herramientas de usuario en el registro de Windows.

BOOL SaveState(LPCTSTR lpszProfileName=NULL);

Parámetros

lpszProfileName
[in] Un ruta de acceso a la clave del registro de Windows.

Valor devuelto

Distinto de cero si el estado se guardó correctamente; de lo contrario, 0.

Comentarios

El método almacena el estado actual del objeto CUserToolsManager en el registro de Windows.

Normalmente no es necesario llamar a este método directamente, CWinAppEx::SaveState lo llama automáticamente como parte del proceso de serialización del área de trabajo de la aplicación.

CUserToolsManager::SetDefExt

Especifica la extensión predeterminada que usa el cuadro de diálogo Archivo abierto (Clase CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogo Personalizar.

void SetDefExt(const CString& strDefExt);

Parámetros

strDefExt
[in] Una cadena de texto que contiene la extensión de nombre de archivo predeterminada.

Comentarios

Llame a este método para especificar una extensión de nombre de archivo predeterminada en el cuadro de diálogo Archivo abierto, que se muestra cuando el usuario selecciona una aplicación para asociarla a la herramienta de usuario. El valor predeterminado es "exe".

CUserToolsManager::SetFilter

Especifica el filtro de archivo que usa el cuadro de diálogo Archivo abierto (Clase CFileDialog) en el campo Comando de la pestaña Herramientas en el cuadro de diálogo Personalizar.

void SetFilter(const CString& strFilter);

Parámetros

strFilter
[in] Especifica el filtro.

Consulte también

Gráfico de jerarquías
Clases
CWinAppEx (clase)
CUserTool (clase)