LPTEXTOUTPROC
Quando o usuário executa uma operação de controle do código-fonte de dentro do ambiente de desenvolvimento integrado (IDE), o plug-in de controle do código-fonte pode querer transmitir mensagens de erro ou status relacionadas à operação. O plug-in pode exibir suas próprias caixas de mensagem para essa finalidade. No entanto, para uma integração mais perfeita, o plug-in pode passar cadeias de caracteres para o IDE, que as exibe em sua maneira nativa de exibir informações de status. O mecanismo para isso é o ponteiro de LPTEXTOUTPROC
função. O IDE implementa essa função (descrita em mais detalhes abaixo) para exibir erro e status.
O IDE passa para o plug-in de controle do código-fonte um ponteiro de função para essa função, como parâmetro lpTextOutProc
, ao chamar o SccOpenProject. Durante uma operação SCC, por exemplo, no meio de uma chamada para o SccGet envolvendo muitos arquivos, o plug-in pode chamar a LPTEXTOUTPROC
função, passando periodicamente cadeias de caracteres para exibição. O IDE pode exibir essas cadeias de caracteres em uma barra de status, em uma janela de saída ou em uma caixa de mensagem separada, conforme apropriado. Opcionalmente, o IDE pode exibir determinadas mensagens com um botão Cancelar . Isso permite que o usuário cancele a operação e dá ao IDE a capacidade de passar essas informações de volta para o plug-in.
Signature
A função de saída do IDE tem a seguinte assinatura:
typedef LONG (*LPTEXTOUTPROC) (
LPSTR display_string,
LONG mesg_type
);
Parâmetros
display_string
Uma cadeia de texto a ser exibida. Essa cadeia de caracteres não deve ser terminada com um retorno de carro ou um feed de linha.
mesg_type
O tipo de mensagem. A tabela a seguir lista os valores com suporte para esse parâmetro.
Valor | Descrição |
---|---|
SCC_MSG_INFO, SCC_MSG_WARNING, SCC_MSG_ERROR |
A mensagem é considerada Informação, Aviso ou Erro. |
SCC_MSG_STATUS |
A mensagem mostra o status e pode ser exibida na barra de status. |
SCC_MSG_DOCANCEL |
Enviado sem cadeia de caracteres de mensagem. |
SCC_MSG_STARTCANCEL |
Começa a exibir um botão Cancelar . |
SCC_MSG_STOPCANCEL |
Pára de exibir um botão Cancelar . |
SCC_MSG_BACKGROUND_IS_CANCELLED |
Pergunta ao IDE se a operação em segundo plano deve ser cancelada: o IDE retorna se a operação foi cancelada, caso contrário, retorna SCC_MSG_RTN_CANCEL SCC_MSG_RTN_OK . O display_string parâmetro é convertido como uma estrutura SccMsgDataIsCancelled , que é fornecida pelo plug-in de controle do código-fonte. |
SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE |
Informa ao IDE sobre um arquivo antes que ele seja recuperado do controle de versão. O display_string parâmetro é convertido como uma estrutura SccMsgDataOnBeforeGetFile , que é fornecida pelo plug-in de controle do código-fonte. |
SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE |
Informa ao IDE sobre um arquivo depois que ele foi recuperado do controle de versão. O display_string parâmetro é convertido como uma estrutura SccMsgDataOnAfterGetFile , que é fornecida pelo plug-in de controle do código-fonte. |
SCC_MSG_BACKGROUND_ON_MESSAGE |
Informa ao IDE o status atual de uma operação em segundo plano. O display_string parâmetro é convertido como uma estrutura SccMsgDataOnMessage , que é fornecida pelo plug-in de controle do código-fonte. |
Valor retornado
Valor | Descrição |
---|---|
SCC_MSG_RTN_OK | A cadeia de caracteres foi exibida ou a operação foi concluída com êxito. |
SCC_MSG_RTN_CANCEL | O usuário deseja cancelar a operação. |
Exemplo
Suponha que o IDE chame o SccGet com vinte nomes de arquivo. O plug-in de controle do código-fonte deseja impedir o cancelamento da operação no meio de um recebimento de arquivo. Depois de obter cada arquivo, ele chama lpTextOutProc
, passando-lhe as informações de status em cada arquivo, e envia uma SCC_MSG_DOCANCEL
mensagem se ele não tem status para relatar. Se, a qualquer momento, o plug-in receber um valor de retorno do SCC_MSG_RTN_CANCEL
IDE, ele cancelará a operação get imediatamente, para que nenhum outro arquivo seja recuperado.
Estruturas
SccMsgDataIsCancelled
typedef struct {
DWORD dwBackgroundOperationID;
} SccMsgDataIsCancelled;
Essa estrutura é enviada com a SCC_MSG_BACKGROUND_IS_CANCELLED
mensagem. Ele é usado para comunicar a ID da operação em segundo plano que foi cancelada.
SccMsgDataOnBeforeGetFile
typedef struct {
DWORD dwBackgroundOperationID;
PCSTR szFile;
} SccMsgDataOnBeforeGetFile;
Essa estrutura é enviada com a SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE
mensagem. Ele é usado para comunicar o nome do arquivo prestes a ser recuperado e a ID da operação em segundo plano que está fazendo a recuperação.
SccMsgDataOnAfterGetFile
typedef struct {
DWORD dwBackgroundOperationID;
PCSTR szFile;
SCCRTN sResult;
} SccMsgDataOnAfterGetFile;
Essa estrutura é enviada com a SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE
mensagem. Ele é usado para comunicar o resultado da recuperação do arquivo especificado, bem como a ID da operação em segundo plano que fez a recuperação. Consulte os valores de retorno para o SccGet para saber o que pode ser dado como resultado.
SccMsgDataOnMessage
typedef struct {
DWORD dwBackgroundOperationID;
PCSTR szMessage;
BOOL bIsError;
} SccMsgDataOnMessage;
Essa estrutura é enviada com a SCC_MSG_BACKGROUND_ON_MESSAGE
mensagem. Ele é usado para comunicar o status atual de uma operação em segundo plano. O status é expresso como uma cadeia de caracteres a ser exibida pelo IDE e bIsError
indica a gravidade da mensagem (TRUE
para uma mensagem de erro; FALSE
para um aviso ou para uma mensagem informativa). O ID da operação em segundo plano que envia o status também é fornecido.
Exemplo de código
Aqui está um breve exemplo de chamada para enviar a mensagem, mostrando como transmitir a estrutura para a SCC_MSG_BACKGROUND_ON_MESSAGE
chamadaLPTEXTOUTPROC
.
LONG SendStatusMessage(
LPTEXTOUTPROC pTextOutProc,
DWORD dwBackgroundID,
LPCTSTR pStatusMsg,
BOOL bIsError)
{
SccMsgDataOnMessage msgData = { 0 };
LONG result = 0;
msgData.dwBackgroundOperationID = dwBackgroundID;
msgData.szMessage = pStatusMsg;
msgData.bIsError = bIsError;
result = pTextOutProc(reinterpret_cast<LPCTSTR>(&msgData), SCC_MSG_BACKGROUND_ON_MESSAGE);
return result;
}