🔧 Drag-and-Drop
Visão Geral#
O sistema de Drag-and-Drop (Arrastar e Largar) é o principal facilitador de fluxo de trabalho no Caffeine Studio. Ele permite que os utilizadores interajam de forma fluida entre os diferentes painéis do editor, como o Asset Browser, o Viewport, o Inspector e o Hierarchy.
Esta funcionalidade visa reduzir o número de cliques necessários para tarefas comuns, como instanciar entidades, atribuir texturas a componentes ou reorganizar a hierarquia de uma cena. A implementação utiliza as APIs nativas do ImGui para gerir o estado de arrasto e os payloads de dados entre widgets.
Implementação#
O sistema baseia-se em DragSource (origem) e DropTarget (destino), identificados por strings de tipo únicas (ex: ASSET_BROWSER_ITEM).
Fluxos de Trabalho Principais#
- Asset Browser → Viewport: Cria uma nova entidade na posição do rato com um
SpriteRendererse o asset for uma imagem. - Asset Browser → Inspector: Atribui um asset (Textura, Shader, Material) a um campo específico de um componente.
- Hierarchy → Hierarchy: Reorganiza a árvore ECS, alterando relações pai/filho.
Código de Exemplo (C++)#
cpp
namespace Caffeine::Editor {
struct DragDropPayload {
std::string Type;
void* Data;
size_t DataSize;
};
class DragDropManager {
public:
// Define um item como arrastável
static void Source(const std::string& type, const void* data, size_t size, const std::string& previewText) {
if (ImGui::BeginDragDropSource()) {
ImGui::SetDragDropPayload(type.c_str(), data, size);
ImGui::Text("%s", previewText.c_str());
ImGui::EndDragDropSource();
}
}
// Define uma área como recetora
template<typename T>
static T* Target(const std::string& type) {
if (ImGui::BeginDragDropTarget()) {
if (const ImGuiPayload* payload = ImGui::AcceptDragDropPayload(type.c_str())) {
return static_cast<T*>(payload->Data);
}
ImGui::EndDragDropTarget();
}
return nullptr;
}
};
}
Integração no Viewport#
cpp
// No loop de renderização do Viewport
if (AssetMetadata* asset = DragDropManager::Target<AssetMetadata>("ASSET_ITEM")) {
if (asset->Type == AssetType::Texture) {
Entity e = scene.CreateEntity(asset->Name);
auto& sprite = e.AddComponent<SpriteRenderer>();
sprite.Texture = asset->Handle;
// Posicionar na coordenada do mundo correspondente ao rato
auto& transform = e.GetComponent<Transform>();
transform.Position = m_ViewportCamera.ScreenToWorld(ImGui::GetMousePos());
}
}
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Preview Visual durante Drag | Mostrar o nome ou ícone do asset junto ao cursor confirma ao utilizador o que está a ser movido. |
| Validação de Tipo no Destino | O campo do Inspector só deve aceitar o "Drop" se o tipo do asset (ex: .png) for compatível com o campo (ex: Texture Slot). |
| Delayed Action | O processamento do drop ocorre apenas no frame em que o botão do rato é solto, evitando operações pesadas durante o movimento. |
Critério de Aceitação#
- [ ] Arrastar uma textura do Asset Browser para o Viewport cria uma entidade com SpriteRenderer.
- [ ] Arrastar um asset para um campo compatível no Inspector (ex: campo "Albedo") atualiza o valor do campo.
- [ ] Arrastar uma entidade no Hierarchy para cima de outra torna-a filha desta última.
- [ ] O cursor muda visualmente quando está sobre um destino válido.
- [ ] Tentar largar um asset num destino incompatível não executa qualquer ação e mostra feedback visual negativo.
Dependências#
- Upstream:
Caffeine::Editor::AssetBrowser,Caffeine::Editor::Inspector - Downstream:
Caffeine::ECS::HierarchySystem
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Asset Browser | Fonte principal de itens para arrastar. |
| ECS Core | Gestão de entidades criadas via drag-and-drop. |
Referências#
- Dear ImGui Drag and Drop API Documentation
- UX patterns in Godot/Unity for asset placement.