노브 API

노브 요소를 관리합니다. HID 기기 축(예: 리듬게임 컨트롤러의 노브)이나 마우스 휠에 바인딩되어 물리 노브와 함께 회전하는 시각화 요소입니다. HID 기기의 버튼은 키보드 키와 완전히 동일하게 매핑·시각화되고, 축은 전용 노브 요소로 시각화됩니다.

식별자

DmNote는 HID 입력에 고정 문자열 식별자를 부여합니다:

버튼 식별자는 키 라벨로 사용되며(일반 키보드 키처럼 매핑 가능, dmn.keys.onRawInput에서 device: 'gamepad'로 전달) 축 식별자는 노브 요소의 axisId에 저장됩니다.

마우스 휠 축은 휠 24칸을 1회전으로 보는 가상 축입니다. sensitivity가 1이면 24칸마다 노브가 360° 돕니다. 휠을 앞쪽(사용자 반대쪽)으로 굴리거나 오른쪽으로 기울이는 방향이 양수입니다. 가로 축도 같은 단위를 쓰지만 실제 회전량과는 관계가 없습니다. macOS에서는 마우스의 HID 보고를 직접 읽기 때문에 트랙패드나 터치 표면 스크롤은 인식하지 않습니다. 휠을 가로채는 마우스 유틸리티를 쓰면 인식되지 않을 수 있습니다.

타입

// KeyPosition의 스타일 필드를 상속 (위치, 크기, 색상, 이미지 등)
// 요소 안정 id(UUID)도 포함: 재정렬·모드 전환에도 같은 노브를 가리키며,
// 전체 프리셋 로드 시에는 새 ID가 발급됩니다 (탭 프리셋은 담긴 컬렉션만)
type KnobItemPosition = KeyPosition & {
  axisId: string; // 바인딩된 축("HIDA:..." 또는 "WHEEL:..."), 미바인딩이면 빈 문자열
  sensitivity: number; // 회전 배율 (기본 1)
  reverse: boolean; // 회전 방향 반전
};
// 축 델타는 내부적으로 축 해상도로 정규화되므로 sensitivity는 기기와
// 무관한 순수 배율입니다: 1 = 물리 1회전 ≈ 화면 1회전,
// 2 = 두 배 회전, 0.5 = 절반.
 
// 탭/모드 id(예: "4key")별 맵
type KnobItemPositions = Record<string, KnobItemPosition[]>;

자주 사용하는 상속 스타일 필드:

• backgroundColor / activeBackgroundColor: 대기 / 회전 중 배경색
• borderColor / activeBorderColor: 대기 / 회전 중 테두리 색상
• borderWidth: 0보다 클 때만 단색 테두리 두께로 사용; 미지정 시 1px 폴백은 그라데이션 테두리에만 적용되고 0이면 두 형식 모두 비활성
• backgroundGradient / activeBackgroundGradient: 배경 그라데이션(GradientSpec, 지정 시 단색보다 우선)
• borderGradient / activeBorderGradient: 테두리 그라데이션(GradientSpec)
• shadow / activeShadow: 대기 / 회전 중 그림자(ElementShadowSpec, color 알파값으로 농도 조절)
• borderRadius: 모서리 반경(px), 미지정 시 원형
• inactiveImage / activeImage: 대기 / 회전 중 커스텀 이미지
• idleTransparent / activeTransparent: 배경 투명 토글

ElementShadowSpec은 enabled, color, offsetX, offsetY, blur로 구성됩니다. 오프셋은 -100100px, 흐림은 0100px 범위입니다.

물리 노브가 회전하는 동안 요소는 키의 눌림처럼 입력(active) 색상/이미지로 전환되며, 누적 회전수 × 360° × sensitivity만큼 회전합니다.

위치 관리

dmn.knobItems.getPositions(): Promise<KnobItemPositions>

전체 탭의 노브 요소 레이아웃을 반환합니다.

const positions = await dmn.knobItems.getPositions();
console.log(positions['4key']); // "4key" 탭의 노브 요소들

dmn.knobItems.updatePositions(positions): Promise<KnobItemPositions>

노브 요소 레이아웃을 교체하고 저장합니다.

const positions = await dmn.knobItems.getPositions();
positions['4key'][0].sensitivity = 2; // 노브 1회전당 화면 2회전
await dmn.knobItems.updatePositions(positions);

dmn.knobItems.onPositionsChanged(callback): Unsubscribe

노브 레이아웃 변경(knobPositions:changed)을 구독합니다.

const unsub = dmn.knobItems.onPositionsChanged((positions) => {
  console.log('노브 레이아웃 변경', positions);
});