Design

Este documento fornece uma visão geral do design da biblioteca, bem como regras gerais para o ajudar você a compreender como interagir com ela.

Objetos

Todos os objetos da biblioteca podem ser divididos nas seguintes categorias:

• objetos de serviço;
• objectos de dados imutáveis.

Os objetos de serviço permitem realizar algumas operações quando os objetos de dados apenas guardam os dados. Os objetos de serviço podem utilizar os objetos de dados.

Objetos como IEngine, IBrowser, IProfile IBrowserSettings, IFrame, IDocument, IJsObject instâncias são objetos de serviço. Enquanto que EngineOptions, Size, Rectangle são objetos de dados imutáveis.

Instanciação

Para criar um objeto de dados imutável ou um objeto de serviço, utilize o seu construtor, builder ou um dos seus métodos estáticos. Eis um exemplo de utilização do construtor:

EngineOptions options = new EngineOptions.Builder 
{
    RenderingMode = RenderingMode.HardwareAccelerated,
    Language = Language.EnglishUs
}.Build();
IEngine engine = EngineFactory.Create(options);

Dim options As EngineOptions = New EngineOptions.Builder With 
{
    .RenderingMode = RenderingMode.HardwareAccelerated,
    .Language = Language.EnglishUs
}.Build()
Dim engine As IEngine = EngineFactory.Create(options)

Destruição

Todos os objetos de serviço que têm de ser eliminados manualmente implementam a interface IDisposable. Para eliminar um objeto de serviço e libertar toda a memória e recursos atribuídos, chame o método IDisposable.Dispose(). Por exemplo:

engine.Dispose();

engine.Dispose()

Alguns objetos de serviço, como o IFrame, podem ser eliminados automaticamente, por exemplo, quando a página Web é descarregada. Estes objetos implementam a interface IAutoDisposable.

Se você utilizar um objeto já descartado, ocorre a ObjectDisposedException.

Relacionamento

O ciclo de vida de um objeto de serviço pode depender do ciclo de vida de outro objeto. Quando o objeto de serviço é eliminado, todos os objetos de serviço que dependem dele são libertados automaticamente. Por exemplo:

• Quando se elimina o IEngine, todas as suas instâncias IBrowser são libertadas automaticamente;
• Quando se elimina o IBrowser, todas as suas instâncias IFrame são eliminadas automaticamente.

Métodos

Os métodos que devolvem uma instância da Task<T> são executados de forma assíncrona. Se o método devolver algum valor, ele é executado de forma síncrona, bloqueando a execução da thread atual até que o valor de retorno seja recebido.

Handlers

Cada objeto que permite o registo de handlers tem as propriedades do tipo IHandler<in T> ou a interface IHandler<in T, out TResult>. Para registrar e anular o registro de um handler, utilize os setters e getters da propriedade.

Existem implementações padrão da interface IHandler<in T, out TResult>:

• Handler<T, TResult> A classe permite envolver lambdas e grupos de métodos;
• A classe AsyncHandler<T, TResult> permite envolver lambdas e grupos de métodos assíncronos ou lambdas e grupos de métodos que devolvem Task<TResult>.

Assíncrono

O exemplo abaixo demonstra como registrar um handler assíncrono que devolve uma Task para fornecer uma resposta de forma assíncrona:

browser.ShowContextMenuHandler =
    new AsyncHandler<ShowContextMenuParameters, ShowContextMenuResponse
    >(ShowContextMenu);

// Um método assíncrono que é declarado na mesma classe.
private async Task<ShowContextMenuResponse> ShowContextMenu(ShowContextMenuParameters p)
{
    // ...
}

browser.ShowContextMenuHandler = 
    New AsyncHandler(Of ShowContextMenuParameters, ShowContextMenuResponse)(
        AddressOf ShowContextMenu)

' Um método assíncrono que é declarado na mesma classe.
private async Task(Of ShowContextMenuResponse) ShowContextMenu(ShowContextMenuParameters p)
{
    ' ...
}

O resultado da tarefa pode ser fornecido de forma assíncrona a partir de um thread diferente.

Fornece uma resposta através do argumento Task devolvido, caso contrário IEngine aguarda a resposta até ao fim.

Síncrono

O exemplo abaixo demonstra como registrar e anular o registro de um Handler regular que devolve a resposta através de um valor de retorno:

browser.CreatePopupHandler =
    new Handler<CreatePopupParameters, CreatePopupResponse>(p =>
    {
        return CreatePopupResponse.Create();
    });

browser.CreatePopupHandler = 
    New Handler(Of CreatePopupParameters, CreatePopupResponse)(Function(p)
        Return CreatePopupResponse.Create()
    End Function)

Threads

A biblioteca não é thread-safe, por isso evite trabalhar com a biblioteca a partir de diferentes threads ao mesmo tempo.